Commit | Line | Data |
8d063cd8 |
1 | |
79072805 |
2 | Perl Kit, Version 5.0 |
8d063cd8 |
3 | |
ed6116ce |
4 | Copyright (c) 1989,1990,1991,1992,1993,1994 Larry Wall |
79072805 |
5 | All rights reserved. |
a687059c |
6 | |
7 | This program is free software; you can redistribute it and/or modify |
d48672a2 |
8 | it under the terms of either: |
9 | |
10 | a) the GNU General Public License as published by the Free |
11 | Software Foundation; either version 1, or (at your option) any |
12 | later version, or |
13 | |
14 | b) the "Artistic License" which comes with this Kit. |
a687059c |
15 | |
16 | This program is distributed in the hope that it will be useful, |
17 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
d48672a2 |
18 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either |
19 | the GNU General Public License or the Artistic License for more details. |
20 | |
21 | You should have received a copy of the Artistic License with this |
22 | Kit, in the file named "Artistic". If not, I'll be glad to provide one. |
a687059c |
23 | |
d48672a2 |
24 | You should also have received a copy of the GNU General Public License |
a687059c |
25 | along with this program; if not, write to the Free Software |
26 | Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. |
8d063cd8 |
27 | |
d48672a2 |
28 | For those of you that choose to use the GNU General Public License, |
29 | my interpretation of the GNU General Public License is that no Perl |
30 | script falls under the terms of the GPL unless you explicitly put |
31 | said script under the terms of the GPL yourself. Furthermore, any |
748a9306 |
32 | object code linked with perl does not automatically fall under the |
d48672a2 |
33 | terms of the GPL, provided such object code only adds definitions |
79220ce3 |
34 | of subroutines and variables, and does not otherwise impair the |
35 | resulting interpreter from executing any standard Perl script. I |
36 | consider linking in C subroutines in this manner to be the moral |
37 | equivalent of defining subroutines in the Perl language itself. You |
38 | may sell such an object file as proprietary provided that you provide |
39 | or offer to provide the Perl source, as specified by the GNU General |
40 | Public License. (This is merely an alternate way of specifying input |
41 | to the program.) You may also sell a binary produced by the dumping of |
42 | a running Perl script that belongs to you, provided that you provide or |
d48672a2 |
43 | offer to provide the Perl source as specified by the GPL. (The |
79220ce3 |
44 | fact that a Perl interpreter and your code are in the same binary file |
45 | is, in this case, a form of mere aggregation.) This is my interpretation |
d48672a2 |
46 | of the GPL. If you still have concerns or difficulties understanding |
47 | my intent, feel free to contact me. Of course, the Artistic License |
48 | spells all this out for your protection, so you may prefer to use that. |
79220ce3 |
49 | |
8d063cd8 |
50 | -------------------------------------------------------------------------- |
51 | |
79072805 |
52 | Perl is a language that combines some of the features of C, sed, awk |
a0d0e21e |
53 | and shell. See the manual page for more hype. There are also two Nutshell |
54 | Handbooks published by O'Reilly & Assoc. See pod/perlbook.pod |
55 | for more information. |
8d063cd8 |
56 | |
57 | Please read all the directions below before you proceed any further, and |
a687059c |
58 | then follow them carefully. |
8d063cd8 |
59 | |
60 | After you have unpacked your kit, you should have all the files listed |
61 | in MANIFEST. |
62 | |
63 | Installation |
64 | |
1aef975c |
65 | 1) Run Configure. This will figure out various things about your |
66 | system. Some things Configure will figure out for itself, other |
67 | things it will ask you about. If the test scripts and programs |
68 | run ok, the defaults will usually be right. It will then proceed to |
69 | make config.h, config.sh, and Makefile. You may have to explicitly |
70 | say sh Configure to ensure that Configure is run under sh. |
c2960299 |
71 | If you're a hotshot, run Configure -d to take all the defaults |
72 | and edit config.sh to patch up any flaws. |
73 | |
74 | If you later make any changes to config.sh, you should propagate |
75 | them to all the .SH files by running Configure -S. |
a0d0e21e |
76 | |
77 | Configure supports a number of useful options. Run Configure -h |
78 | to get a listing. To compile with gcc, for example, you can run |
16d20bd9 |
79 | Configure -Dcc=gcc, or answer 'gcc' at the cc prompt. |
80 | |
c2960299 |
81 | If you wish to use gcc (or another alternative compiler) |
16d20bd9 |
82 | you should use Configure -Dcc=gcc. That way, the the hints |
83 | files can set appropriate defaults. |
c2960299 |
84 | |
85 | By default, perl will be installed in /usr/local/{bin, lib, man}. |
86 | You can specify a different 'prefix' for the default installation |
87 | directory, when Configure prompts you or by using the Configure |
88 | command line option -Dprefix='/some/directory'. |
232e078e |
89 | |
c2960299 |
90 | By default, perl will use dynamic extensions if your system |
91 | supports it. If you want to force perl to be compiled statically, |
92 | you can either choose this when Configure prompts you or by using |
93 | the Configure command line option -Uusedl |
94 | |
232e078e |
95 | If you change compilers or make other significant changes, you should |
96 | probably _not_ re-use your old config.sh. Simply remove it or |
c2960299 |
97 | rename it, e.g. mv config.sh config.sh.old. Then rerun Configure |
98 | with the options you want to use. |
a0d0e21e |
99 | |
100 | You can also supply a file config.over to over-ride Configure's |
101 | guesses. It will get loaded up at the very end, just before |
102 | config.sh is created. |
8d063cd8 |
103 | |
104 | You might possibly have to trim # comments from the front of Configure |
105 | if your sh doesn't handle them, but all other # comments will be taken |
106 | care of. |
107 | |
16d20bd9 |
108 | (If you don't have sh, you'll have to copy the sample file config_H to |
8d063cd8 |
109 | config.h and edit the config.h to reflect your system's peculiarities.) |
110 | |
111 | 2) Glance through config.h to make sure system dependencies are correct. |
112 | Most of them should have been taken care of by running the Configure script. |
113 | |
114 | If you have any additional changes to make to the C definitions, they |
1c3d792e |
115 | can be done in cflags.SH. For instance, to turn off the optimizer |
a0d0e21e |
116 | on toke.c, find the line in the switch structure for toke.c and |
117 | put the command optimize='-g' before the ;;. To change the C flags |
c2960299 |
118 | for all the files, edit config.sh and change either $ccflags or $optimize, |
119 | and then re-run Configure -S ; make depend. |
120 | |
8d063cd8 |
121 | |
122 | 3) make depend |
123 | |
124 | This will look for all the includes and modify Makefile accordingly. |
125 | Configure will offer to do this for you. |
126 | |
127 | 4) make |
128 | |
129 | This will attempt to make perl in the current directory. |
130 | |
d8f2e4cc |
131 | If you can't compile successfully, try adding a -DCRIPPLED_CC flag. |
132 | (Just because you get no errors doesn't mean it compiled right!) |
133 | This simplifies some complicated expressions for compilers that |
134 | get indigestion easily. If that has no effect, try turning off |
135 | optimization. If you have missing routines, you probably need to |
136 | add some library or other, or you need to undefine some feature that |
137 | Configure thought was there but is defective or incomplete. |
138 | |
139 | Some compilers will not compile or optimize the larger files without |
140 | some extra switches to use larger jump offsets or allocate larger |
1c3d792e |
141 | internal tables. You can customize the switches for each file in |
142 | cflags.SH. It's okay to insert rules for specific files into |
b6ccd89c |
143 | Makefile.SH, since a default rule only takes effect in the |
d8f2e4cc |
144 | absence of a specific rule. |
145 | |
16d20bd9 |
146 | If you used a hint file, try reading the comments in the hint file |
147 | for further tips and information. |
148 | |
149 | If you can successfully build miniperl, but the process crashes |
150 | during the building of extensions, you should run |
151 | make minitest |
152 | to test your version of miniperl. |
153 | |
154 | Some additional things that have been reported for either perl4 or |
155 | perl5: |
1c3d792e |
156 | |
a0d0e21e |
157 | Genix may need to use libc rather than libc_s, or #undef VARARGS. |
16d20bd9 |
158 | |
449aadca |
159 | NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR. |
16d20bd9 |
160 | |
5303340c |
161 | UTS may need one or more of -DCRIPPLED_CC, -K or -g, and undef LSTAT. |
16d20bd9 |
162 | |
a0d0e21e |
163 | If you get syntax errors on '(', try -DCRIPPLED_CC. |
16d20bd9 |
164 | |
a0d0e21e |
165 | Machines with half-implemented dbm routines will need to #undef I_ODBM |
16d20bd9 |
166 | |
a0d0e21e |
167 | SCO prior to 3.2.4 may be missing dbmclose(). An upgrade to 3.2.4 |
168 | that includes libdbm.nfs (which includes dbmclose()) may be available. |
16d20bd9 |
169 | |
f1ca563b |
170 | If you get duplicates upon linking for malloc et al, say -DHIDEMYMALLOC. |
16d20bd9 |
171 | |
a0d0e21e |
172 | If you get duplicate function definitions (a perl function has the |
173 | same name as another function on your system) try -DEMBED. |
16d20bd9 |
174 | |
ecfc5424 |
175 | If you get varags problems with gcc, be sure that gcc is installed |
176 | correctly. When using gcc, you should probably have i_stdarg='define' |
16d20bd9 |
177 | and i_varags='undef' in config.sh. The problem is usually solved |
178 | by running fixincludes correctly. |
179 | |
232e078e |
180 | If you wish to use dynamic loading on SunOS or Solaris, and you |
181 | have GNU as and GNU ld installed, you may need to add -B/bin/ to |
182 | your $ccflags and $ldflags so that the system's versions of as |
183 | and ld are used. |
d8f2e4cc |
184 | |
16d20bd9 |
185 | If you run into dynamic loading problems, check your setting of |
186 | the LD_LIBRARY_PATH environment variable. Perl should build |
187 | fine with LD_LIBRARY_PATH unset, though that may depend on details |
188 | of your local set-up. |
189 | |
8d063cd8 |
190 | 5) make test |
191 | |
192 | This will run the regression tests on the perl you just made. |
193 | If it doesn't say "All tests successful" then something went wrong. |
378cc40b |
194 | See the README in the t subdirectory. Note that you can't run it |
03a14243 |
195 | in background if this disables opening of /dev/tty. If "make test" |
196 | bombs out, just cd to the t directory and run TEST by hand to see if |
1c3d792e |
197 | it makes any difference. If individual tests bomb, you can run |
198 | them by hand, e.g., ./perl op/groups.t |
8d063cd8 |
199 | |
200 | 6) make install |
201 | |
16d20bd9 |
202 | This will put perl into a public directory (such as |
203 | /usr/local/bin). It will also try to put the man pages in a |
204 | reasonable place. It will not nroff the man page, however. You |
205 | may need to be root to run make install. If you are not root, you |
206 | must own the directories in question and you should ignore any |
207 | messages about chown not working. |
8d063cd8 |
208 | |
16d20bd9 |
209 | make install will install the following: |
94b6baf5 |
210 | perl, |
211 | perl5.nnn where nnn is the current release number. This |
212 | will be a link to perl. |
213 | suidperl, |
214 | sperl5.nnn If you requested setuid emulation. |
215 | a2p awk-to-perl translator |
216 | cppstdin This is used by perl -P, if your cc -E can't |
217 | read from stdin. |
218 | c2ph, pstruct Scripts for handling C structures in header files. |
219 | s2p sed-to-perl translator |
220 | find2perl find-to-perl translator |
221 | h2xs Converts C .h header files to Perl extensions. |
16d20bd9 |
222 | perldoc Tool to read perl's pod documentation. |
232e078e |
223 | pod2html, Converters from perl's pod documentation format |
224 | pod2latex, and to other useful formats. |
225 | pod2man |
94b6baf5 |
226 | |
227 | library files in $privlib and $archlib specified to |
228 | Configure, usually under /usr/local/lib/perl5/. |
229 | man pages in the location specified to Configure, usually |
230 | something like /usr/local/man/man1. |
16d20bd9 |
231 | module in the location specified to Configure, usually |
232 | man pages under /usr/local/lib/perl5/man/man3. |
233 | pod/*.pod in $privlib/pod/. |
94b6baf5 |
234 | |
235 | Perl's *.h header files and the libperl.a library are also |
236 | installed under $archlib so that you may later build new |
237 | extensions even if the Perl source is no longer available. |
238 | |
239 | make install may also offer to install perl in a "standard" location. |
240 | |
a0d0e21e |
241 | Most of the documentation in the pod/ directory is also available |
16d20bd9 |
242 | in HTML and LaTeX format. Type |
a0d0e21e |
243 | cd pod; make html; cd .. |
16d20bd9 |
244 | to generate the html versions, and |
245 | cd pod; make tex; cd .. |
246 | to generate the LaTeX versions. |
a0d0e21e |
247 | |
248 | 7) Read the manual entries before running perl. |
8d063cd8 |
249 | |
a687059c |
250 | 8) IMPORTANT! Help save the world! Communicate any problems and suggested |
fe14fcc3 |
251 | patches to me, lwall@netlabs.com (Larry Wall), so we can |
8d063cd8 |
252 | keep the world in sync. If you have a problem, there's someone else |
253 | out there who either has had or will have the same problem. |
254 | |
255 | If possible, send in patches such that the patch program will apply them. |
256 | Context diffs are the best, then normal diffs. Don't send ed scripts-- |
d48672a2 |
257 | I've probably changed my copy since the version you have. It's also |
258 | helpful if you send the output of "uname -a". |
8d063cd8 |
259 | |
d8f2e4cc |
260 | Watch for perl patches in comp.lang.perl. Patches will generally be |
8d063cd8 |
261 | in a form usable by the patch program. If you are just now bringing up |
262 | perl and aren't sure how many patches there are, write to me and I'll |
263 | send any you don't have. Your current patch level is shown in patchlevel.h. |
264 | |
a687059c |
265 | |
266 | Just a personal note: I want you to know that I create nice things like this |
267 | because it pleases the Author of my story. If this bothers you, then your |
268 | notion of Authorship needs some revision. But you can use perl anyway. :-) |
269 | |
270 | The author. |