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