Commit | Line | Data |
748a9306 |
1 | Last revised: 08-Feb-1995 by Charles Bailey bailey@genetics.upenn.edu |
a0d0e21e |
2 | |
748a9306 |
3 | The VMS port of Perl is still under development. At this time, the Perl |
a0d0e21e |
4 | binaries built under VMS handle internal operations properly, for the most |
5 | part, as well as most of the system calls which have close equivalents under |
6 | VMS. There are still some incompatibilities in process handling (e.g the |
7 | fork/exec model for creating subprocesses doesn't do what you might expect |
748a9306 |
8 | under Unix), and there remain some file handling differences from Unix. Over |
9 | the longer term, we'll try to get many of the useful VMS system services |
10 | integrated as well, depending on time and people available. Of course, if |
11 | you'd like to add something yourself, or join the porting team, we'd love to |
12 | have you! |
a0d0e21e |
13 | |
14 | The current sources and build procedures have been tested on a VAX using VAXC |
748a9306 |
15 | and on an AXP using DECC. If you run into problems with other compilers, |
a0d0e21e |
16 | please let us know. |
17 | |
748a9306 |
18 | Note to DECC users: Some early versions of the DECCRTL contained a few bugs |
19 | which affect Perl performance: |
20 | - Newlines are lost on I/O through pipes, causing lines to run together. |
21 | This shows up as RMS RTB errors when reading from a pipe. You can |
22 | work around this by having one process write data to a file, and |
23 | then having the other read the file, instead of the pipe. |
24 | - The modf() routine returns a non-integral value for some values above |
25 | INT_MAX; the Perl "int" operator will return a non-integral value in |
26 | these cases. |
27 | Both of these bugs have been fixed in later releases of the DECCRTL, but some |
28 | systems running AXP/VMS 1.5 still have the old RTLs. |
a0d0e21e |
29 | |
30 | * Other software required |
31 | |
32 | At the moment, in addition to basic VMS, you'll need two things: |
33 | - a C compiler: VAXC, DECC, or gcc for the VAX; DECC for the AXP |
34 | - a make tool: DEC's MMS or the free analog MMK (available from ftp.spc.edu) |
35 | or a standard make utility (e.g. GNU make, also available from |
36 | ftp.spc.edu). |
37 | In addition, you may include socket support if you have a IP stack running |
38 | on your system. See the topic "Socket support" for more information. |
39 | |
40 | * Socket support |
41 | |
748a9306 |
42 | Perl includes a number of IP socket routines among its builtin functions, |
43 | which are available if you choose to compile Perl with socket support. Since |
a0d0e21e |
44 | IP networking is an optional addition to VMS, there are several different IP |
748a9306 |
45 | stacks available, it's difficult to automate the process of building Perl with |
a0d0e21e |
46 | socket support in a way which will work on all systems. |
47 | |
748a9306 |
48 | By default, Perl is built without IP socket support. If you define the macro |
a0d0e21e |
49 | SOCKET when invoking MMS, however, socket support will be included. As |
748a9306 |
50 | distributed, Perl for VMS includes support for the SOCKETSHR socket library, |
a0d0e21e |
51 | which is layered on MadGoat software's vendor-independent NETLIB interface. |
748a9306 |
52 | This provides support for all socket calls used by Perl except the |
a0d0e21e |
53 | [g|s]et*ent() routines, which are replaced for the moment by stubs which |
748a9306 |
54 | generate a fatal error if a Perl script attempts to call one of these routines. |
55 | If you'd like to link Perl directly to your IP stack to take advantage of these |
a0d0e21e |
56 | routines or to eliminate the intermediate NETLIB, then make the following |
57 | changes: |
58 | - In Descrip.MMS, locate the section beginning with .ifdef SOCKET, and |
59 | change the SOCKLIB macro so that it translates to the filespec of your |
60 | IP stack's socket library. This will be added to the RTL options file. |
61 | - Edit the file SockAdapt.H in the [.VMS] subdirectory so that it |
62 | includes the In.H, NetDb.H, and, if necessary, Errno.H header files |
63 | for your IP stack, or so that it declares the standard TCP/IP data |
64 | structures appropriately (see the distributed copy of SockAdapt.H |
748a9306 |
65 | for a collection of the structures needed by Perl.) You should also |
a0d0e21e |
66 | define any logical names necessary to find these files before invoking |
748a9306 |
67 | MMS to build Perl. |
a0d0e21e |
68 | - Edit the file SockAdapt.C in the [.VMS] subdirectory so that it |
69 | contains routines which substitute for any IP library routines |
748a9306 |
70 | required by Perl which your IP stack does not provide. This may |
a0d0e21e |
71 | require a little trial and error; we'll try to compile a complete |
748a9306 |
72 | list soon of socket routines required by Perl. |
a0d0e21e |
73 | |
748a9306 |
74 | * Building Perl under VMS |
a0d0e21e |
75 | |
748a9306 |
76 | Since you're reading this, presumably you've unpacked the Perl distribution |
a0d0e21e |
77 | into its directory tree, in which you will find a [.vms] subdirectory below |
78 | the directory in which this file is found. If this isn't the case, then you'll |
79 | need to unpack the distribution properly, or manually edit Descrip.MMS or |
748a9306 |
80 | the VMS Makefile to alter directory paths as necessary. (I'd advise using the |
a0d0e21e |
81 | `normal' directory tree, at least for the first time through.) This |
82 | subdirectory contains several files, among which are the following: |
83 | Config.VMS - A template C header file set up for VMS. |
748a9306 |
84 | Descrip.MMS - The MMS/MMK dependency file for building Perl |
85 | GenConfig.Pl - A Perl script to generate Config.SH retrospectively |
a0d0e21e |
86 | from Config.VMS, since the Configure shell script which |
87 | normally generates Config.SH doesn't run under VMS. |
88 | GenOpt.Com - A little DCL procedure used to write some linker options |
89 | files, since not all make utilities can do this easily. |
748a9306 |
90 | Gen_ShrFls.Pl - A Perl script which generates linker options files and |
a0d0e21e |
91 | MACRO declarations for PerlShr.Exe. |
748a9306 |
92 | Makefile - The make dependency file for building Perl |
93 | MMS2Make.Pl - A Perl script used to generate Makefile from Descrip.MMS |
a0d0e21e |
94 | VMSish.H - C header file containing VMS-specific definitions |
95 | VMS.C - C source code for VMS-specific routines |
748a9306 |
96 | WriteMain.Pl - A Perl script used to generate perlmain.c during the build. |
a0d0e21e |
97 | There may also be other files pertaining to features under development; for the |
98 | most part, you can ignore them. |
99 | |
748a9306 |
100 | Config.VMS and Decrip.MMS/Makefile are set up to build a version of Perl which |
a0d0e21e |
101 | includes all features known to work when this release was assembled. If you |
102 | have code at your site which would support additional features (e.g. emulation |
103 | of Unix system calls), feel free to make the appropriate changes to these |
748a9306 |
104 | files. (Note: Do not use or edit config.h in the main Perl source directory; |
a0d0e21e |
105 | it is superseded by the current Config.VMS during the build.) You may also |
748a9306 |
106 | wish to make site-specific changes to Descrip.MMS or Makefile to reflect local |
a0d0e21e |
107 | conventions for naming of files, etc. |
108 | |
748a9306 |
109 | At the moment, system-specific information which becomes part of the Perl |
a0d0e21e |
110 | Config extension is hard-coded into the file genconfig.pl in the vms |
748a9306 |
111 | subdirectory. Before you build Perl, you should make any changes to the list |
a0d0e21e |
112 | at the end of this file necessary to reflect your system (e.g your hostname and |
113 | VMS version). |
114 | |
115 | Examine the information at the beginning of Descrip.MMS for information about |
748a9306 |
116 | specifying alternate C compilers or building a version of Perl with debugging |
a0d0e21e |
117 | support. For instance, if you want to use DECC, you'll need to include the |
118 | /macro="decc=1" qualifier to MMS (If you're using make, these options are not |
119 | supported.) If you're on an AXP system, define the macro __AXP__ (MMK does |
120 | this for you), and DECC will automatically be selected. |
121 | |
748a9306 |
122 | To start the build, set default to the main source directory. Since |
123 | Descrip.MMS assumes that VMS commands have their usual meaning, and makes use |
124 | of command-line macros, you may want to be certain that you haven't defined DCL |
125 | symbols which would interfere with the build. Then, if you are using MMS or |
126 | MMK, say |
a0d0e21e |
127 | $ MMS/Descrip=[.VMS] ! or MMK |
748a9306 |
128 | If you are using make, say |
129 | $ Make -f [.VMS]Makefile |
130 | Note that the Makefile doesn't support conditional compilation, is |
a0d0e21e |
131 | set up to use VAXC on a VAX, and does not include socket support. You can |
748a9306 |
132 | either edit the Makefile by hand, using Descrip.MMS as a guide, or use the |
133 | Makefile to build Miniperl.Exe, and then run the Perl script MMS2Make.pl, |
a0d0e21e |
134 | found in the [.VMS] subdirectory, to generate a new Makefile with the options |
135 | appropriate to your site. |
136 | |
137 | Note for sites using early versions of DECC: A bug in some versions of the |
138 | DECC RTL causes newlines to be lost when writing to a pipe. This causes |
139 | Gen_ShrFls.pl to fail, since it can't read the preprocessor output to identify |
140 | global variables and routines. You can work around this problem by defining |
141 | the macro DECC_PIPES_BROKEN when you invoke MMS or MMK. |
142 | |
143 | This will build the following files: |
144 | Miniperl.Exe - a stand-alone version of without any extensions. |
748a9306 |
145 | Miniperl has all the intrinsic capabilities of Perl, |
a0d0e21e |
146 | but cannot make use of the DynaLoader or any |
147 | extensions which use XS code. |
748a9306 |
148 | PerlShr.Exe - a shareable image containing most of Perl's internal |
a0d0e21e |
149 | routines and global variables. Perl.Exe is linked to |
150 | this image, as are all dynamic extensions, so everyone's |
151 | using the same set of global variables and routines. |
748a9306 |
152 | Perl.Exe - the main Perl executable image. It's contains the |
a0d0e21e |
153 | main() routine, plus code for any statically linked |
154 | extensions. |
155 | PerlShr_Attr.Opt - A linker options file which specifies psect attributes |
156 | matching those in PerlShr.Exe. It should be used when |
157 | linking images against PerlShr.Exe |
748a9306 |
158 | PerlShr_Bld.Opt - A linker options file which specifies various things |
159 | used to build PerlShr.Exe. It should be used when |
160 | rebuilding PerlShr.Exe via MakeMaker-produced |
161 | Descrip.MMS files for static extensions. |
162 | [.Lib]Config.pm - the Perl extension which saves configuration information |
163 | about Perl and your system. |
164 | [.lib]DynaLoader.pm - The Perl extension which performs dynamic linking of |
a0d0e21e |
165 | shareable images for extensions. |
166 | There are, of course, a number of other files created for use during the build. |
167 | Once you've got the binaries built, you may wish to `build' the `tidy' or |
168 | `clean' targets to remove extra files. |
169 | |
170 | |
748a9306 |
171 | * Installing Perl once it's built |
a0d0e21e |
172 | |
173 | Once the build is complete, you'll need to do the following: |
174 | - Put PerlShr.Exe in a common directory, and make it world-readable. |
175 | If you place it in a location other than Sys$Share, you'll need to |
176 | define the logical name PerlShr to point to the image. |
177 | - Put Perl.Exe in a common directory, and make it world executable |
748a9306 |
178 | - Define a foreign command to invoke Perl, using a statement like |
a0d0e21e |
179 | $ Perl == "$dev:[dir]Perl.Exe" |
748a9306 |
180 | - Create a world-readable directory tree for Perl library modules, |
a0d0e21e |
181 | scripts, and what-have-you, and define PERL_ROOT as a rooted logical |
748a9306 |
182 | name pointing to the top of this tree (i.e. if your Perl files were |
183 | going to live in DKA1:[Util.Perl5...], then you should |
184 | $ Define/Translation=Concealed Perl_Root DKA1:[Util.Perl5.] |
185 | (Be careful to follow the rules for rooted logical names; in particular, |
186 | remember that a rooted logical name cannot have as its device portion |
187 | another rooted logical name - you've got to supply the actual device name |
188 | and directory path to the root directory.) |
a0d0e21e |
189 | - Define the logical name PERLSHR as the full file specification of |
190 | PERLSHR.EXE, so executable images linked to it can find it. Alternatively, |
191 | you can justput PERLSHR.EXE int SYS$SHARE. |
192 | - Place the files from the [.lib] subdirectory in the distribution package |
193 | into a [.lib] subdirectory off the root directory described above. |
748a9306 |
194 | - Most of the Perl documentation lives in the [.pod] subdirectory, and |
a0d0e21e |
195 | is written in a simple markup format which can be easily read. In this |
196 | directory as well are pod2man and pod2html translators to reformat the |
197 | docs for common display engines; a pod2hlp translator is under development. |
748a9306 |
198 | Information on Perl can also be gleaned from the files in the [.doc] |
a0d0e21e |
199 | subdirectory (internals documents and summaries of changes), and from |
200 | the test scripts in the [.t...] subdirectories. |
201 | For now, that's it. |
202 | |
203 | |
204 | * For more information |
205 | |
748a9306 |
206 | If you're interested in more information on Perl in general, consult the Usenet |
a0d0e21e |
207 | newsgroup comp.lang.perl. The FAQ for that group provides pointers to other |
748a9306 |
208 | online sources of information, as well as books describing Perl in depth. |
a0d0e21e |
209 | |
748a9306 |
210 | If you're interested in up-to-date information on Perl development and |
a0d0e21e |
211 | internals, you might want to subscribe to the perl5-porters mailing list. You |
748a9306 |
212 | can do this by sending a message to perl5-porters-request@nicoh.com, containing |
a0d0e21e |
213 | the single line |
214 | subscribe perl5-porters Your Name Here |
215 | This is a moderately high-volume list at the moment (25-50 messages/day). |
216 | |
217 | Finally, if you're interested in ongoing information about the VMS port, you |
218 | can subscribe to the VMSperl mailing list by sending a request to |
219 | bailey@genetics.upenn.edu (it's to a human, not a list server - this is a small |
220 | operation at the moment). And, as always, we welcome any help or code you'd |
221 | like to offer - you can send mail to bailey@genetics.upenn.edu or directly to |
222 | the VMSperl list at vmsperl@genetics.upenn.edu. |
223 | |
748a9306 |
224 | Good luck using Perl. Please let us know how it works for you - we can't |
a0d0e21e |
225 | guarantee that we'll be able to fix bugs quickly, but we'll try, and we'd |
226 | certainly like to know they're out there. |
227 | |
228 | |
229 | * Acknowledgements |
230 | |
231 | There are, of course, far too many people involved in the porting and testing |
748a9306 |
232 | of Perl to mention everyone who deserves it, so please forgive us if we've |
a0d0e21e |
233 | missed someone. That said, special thanks are due to the following: |
748a9306 |
234 | Tim Adye <T.J.Adye@rl.ac.uk> |
235 | for the VMS emulations of getpw*() |
a0d0e21e |
236 | David Denholm <denholm@conmat.phys.soton.ac.uk> |
237 | for extensive testing and provision of pipe and SocketShr code, |
238 | Mark Pizzolato <mark@infocomm.com> |
239 | for the getredirection() code |
240 | Rich Salz <rsalz@bbn.com> |
241 | for readdir() and related routines |
242 | Denis Haskin <DWH@epub.ziff.com> |
748a9306 |
243 | for work on a pod-to-hlp translator for the Perl documentation |
a0d0e21e |
244 | Richard Dyson <dyson@blaze.physics.uiowa.edu> and |
245 | Kent Covert <kacovert@miavx1.acs.muohio.edu> |
246 | for additional testing on the AXP. |
247 | and to the entire VMSperl group for useful advice and suggestions. In addition |
248 | the perl5-porters, especially Andy Dougherty <doughera@lafcol.lafayette.edu> |
249 | and Tim Bunce <Tim.Bunce@ig.co.uk>, deserve credit for their creativity and |
250 | willingness to work with the VMS newcomers. Finally, the greatest debt of |
251 | gratitude is due to Larry Wall <lwall@netlabs.com>, for having the ideas which |
252 | have made our sleepless nights possible. |
253 | |
254 | Thanks, |
255 | The VMSperl group |