=head1 NAME
-Pumpkin - Notes on handling the Perl Patch Pumpkin
+Pumpkin - Notes on handling the Perl Patch Pumpkin And Porting Perl
=head1 SYNOPSIS
Archives of the list are held at:
- http://www.rosat.mpe-garching.mpg.de/mailing-lists/perl-porters/
+ http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/
=head1 How are Perl Releases Numbered?
C<$1> in the pattern is always an even number for maintenance
versions, and odd for developer releases.
-In the past it has been observed that pumkings tend to invent new
+In the past it has been observed that pumpkings tend to invent new
naming conventions on the fly. If you are a pumpking, before you
invent a new name for any of the three types of perl distributions,
please inform the guys from the CPAN who are doing indexing and
If feasible, try to keep filenames 8.3-compliant to humor those poor
souls that get joy from running Perl under such dire limitations.
There's a script, check83.pl, for keeping your nose 8.3-clean.
+In a similar vein, do not create files or directories which differ only
+in case (upper versus lower).
=head2 Seek consensus on major changes
File::Copy to become aware of your native filesystem syntax and
peculiarities.
+Remember to have a $VERSION in the modules. You can use the
+Porting/checkVERSION.pl script for checking this.
+
=item documentation
If your operating system comes from outside UNIX you almost certainly
incorporate that feedback quickly (e.g. within 1 week) and send out a
second patch.
+If you update the subversion number, you may need to change the version
+number near the top of the F<Changes> file.
+
=head2 run metaconfig
If you need to make changes to Configure or config_h.SH, it may be best to
mv y.tab.c perly.c
patch perly.c <perly_c.diff
# manually apply any failed hunks
- diff -c2 perly.c.orig perly.c >perly_c.diff
+ diff -c perly.c.orig perly.c >perly_c.diff
One chunk of lines that often fails begins with
separately in the patch file (or both). There is no disagreement that
detailed descriptions ought to be easily available somewhere.
+If you update the subversion number in F<patchlevel.h>, you may need
+to change the version number near the top of the F<Changes> file.
+
=head2 Todo
-The F<Todo> file contains a roughly-catgorized unordered list of
-aspects of Perl that could use enhancement, features that could be
-added, areas that could be cleaned up, and so on. During your term as
-pumpkin-holder, you will probably address some of these issues, and
-perhaps identify others which, while you decide not to address them
-this time around, may be tackled in the future. Update the file
-reflect the situation as it stands when you hand over the pumpkin.
+The F<pod/perltodo.pod> file contains a roughly-categorized unordered
+list of aspects of Perl that could use enhancement, features that could
+be added, areas that could be cleaned up, and so on. During your term
+as pumpkin-holder, you will probably address some of these issues, and
+perhaps identify others which, while you decide not to address them this
+time around, may be tackled in the future. Update the file to reflect
+the situation as it stands when you hand over the pumpkin.
You might like, early in your pumpkin-holding career, to see if you
can find champions for partiticular issues on the to-do list: an issue
owned is an issue more likely to be resolved.
-There are also some more porting-specific L<Todo> items later in this
+There are also some more porting-specific L</Todo> items later in this
file.
=head2 OS/2-specific updates
make clean
make miniperl
- make all OPTIMIZE=-DCHECK_FORMAT >& make.log
+ make all OPTIMIZE='-DCHECK_FORMAT -Wformat' >& make.log
=item *
(-Wformat support by Robin Barker.)
+=item gcc -ansi -pedantic
+
+Configure -Dgccansipedantic [ -Dcc=gcc ] will enable (via the cflags script,
+not $Config{ccflags}) the gcc strict ANSI C flags -ansi and -pedantic for
+the compilation of the core files on platforms where it knows it can
+do so (like Linux, see cflags.SH for the full list), and on some
+platforms only one (Solaris can do only -pedantic, not -ansi).
+The flag -DPERL_GCC_PEDANTIC also gets added, since gcc does not add
+any internal cpp flag to signify that -pedantic is being used, as it
+does for -ansi (__STRICT_ANSI__).
+
+Note that the -ansi and -pedantic are enabled only for version 3 (and
+later) of gcc, since even gcc version 2.95.4 finds lots of seemingly
+false "value computed not used" errors from Perl.
+
+The -ansi and -pedantic are useful in catching at least the following
+nonportable practices:
+
+=over 4
+
+=item *
+
+gcc-specific extensions
+
+=item *
+
+lvalue casts
+
+=item *
+
+// C++ comments
+
+=item *
+
+enum trailing commas
+
+=back
+
+The -Dgccansipedantic should be used only when cleaning up the code,
+not for production builds, since otherwise gcc cannot inline certain
+things.
+
=back
=head1 Running Purify
probably have been named something to do with overriding though. Since
it's undocumented we could still change it... :-)
-Given that it's already there, you can use it to override
-distribution modules. If you do
+Given that it's already there, you can use it to override distribution modules.
+One way to do that is to add
- sh Configure -Dccflags='-DAPPLLIB_EXP=/my/override'
+ ccflags="$ccflags -DAPPLLIB_EXP=\"/my/override\""
+
+to your config.over file. (You have to be particularly careful to get the
+double quotes in. APPLLIB_EXP must be a valid C string. It might
+actually be easier to just #define it yourself in perl.c.)
-then perl.c will put /my/override ahead of ARCHLIB and PRIVLIB.
+Then perl.c will put /my/override ahead of ARCHLIB and PRIVLIB. Perl will
+also search architecture-specific and version-specific subdirectories of
+APPLLIB_EXP.
=head2 Shared libperl.so location
=back
+=head2 Indentation style
+
+Over the years Perl has become a mishmash of
+various indentation styles, but the original "Larry style" can
+probably be restored with (GNU) indent somewhat like this:
+
+ indent -kr -nce -psl -sc
+
+A more ambitious solution would also specify a list of Perl specific
+types with -TSV -TAV -THV .. -TMAGIC -TPerlIO ... but that list would
+be quite ungainly. Also note that GNU indent also doesn't do aligning
+of consecutive assignments, which would truly wreck the layout in
+places like sv.c:Perl_sv_upgrade() or sv.c:Perl_clone_using().
+Similarly nicely aligned &&s, ||s and ==s would not be respected.
+
=head1 Upload Your Work to CPAN
You can upload your work to CPAN if you have a CPAN id. Check out
items that merit consideration. This list isn't exhaustive, it's just
what I came up with off the top of my head.
+=head2 Adding missing library functions to Perl
+
+The perl Configure script automatically determines which headers and
+functions you have available on your system and arranges for them to be
+included in the compilation and linking process. Occasionally, when porting
+perl to an operating system for the first time, you may find that the
+operating system is missing a key function. While perl may still build
+without this function, no perl program will be able to reference the missing
+function. You may be able to write the missing function yourself, or you
+may be able to find the missing function in the distribution files for
+another software package. In this case, you need to instruct the perl
+configure-and-build process to use your function. Perform these steps.
+
+=over 3
+
+=item *
+
+Code and test the function you wish to add. Test it carefully; you will
+have a much easier time debugging your code independently than when it is a
+part of perl.
+
+=item *
+
+Here is an implementation of the POSIX truncate function for an operating
+system (VOS) that does not supply one, but which does supply the ftruncate()
+function.
+
+ /* Beginning of modification history */
+ /* Written 02-01-02 by Nick Ing-Simmons (nick@ing-simmons.net) */
+ /* End of modification history */
+
+ /* VOS doesn't supply a truncate function, so we build one up
+ from the available POSIX functions. */
+
+ #include <fcntl.h>
+ #include <sys/types.h>
+ #include <unistd.h>
+
+ int
+ truncate(const char *path, off_t len)
+ {
+ int fd = open(path,O_WRONLY);
+ int code = -1;
+ if (fd >= 0) {
+ code = ftruncate(fd,len);
+ close(fd);
+ }
+ return code;
+ }
+
+Place this file into a subdirectory that has the same name as the operating
+system. This file is named perl/vos/vos.c
+
+=item *
+
+If your operating system has a hints file (in perl/hints/XXX.sh for an
+operating system named XXX), then start with it. If your operating system
+has no hints file, then create one. You can use a hints file for a similar
+operating system, if one exists, as a template.
+
+=item *
+
+Add lines like the following to your hints file. The first line
+(d_truncate="define") instructs Configure that the truncate() function
+exists. The second line (archobjs="vos.o") instructs the makefiles that the
+perl executable depends on the existence of a file named "vos.o". (Make
+will automatically look for "vos.c" and compile it with the same options as
+the perl source code). The final line ("test -h...") adds a symbolic link
+to the top-level directory so that make can find vos.c. Of course, you
+should use your own operating system name for the source file of extensions,
+not "vos.c".
+
+ # VOS does not have truncate() but we supply one in vos.c
+ d_truncate="define"
+ archobjs="vos.o"
+
+ # Help gmake find vos.c
+ test -h vos.c || ln -s vos/vos.c vos.c
+
+The hints file is a series of shell commands that are run in the top-level
+directory (the "perl" directory). Thus, these commands are simply executed
+by Configure at an appropriate place during its execution.
+
+=item *
+
+At this point, you can run the Configure script and rebuild perl. Carefully
+test the newly-built perl to ensure that normal paths, and error paths,
+behave as you expect.
+
+=back
+
=head2 Good ideas waiting for round tuits
=over 4
=head1 AUTHORS
-Original author: Andy Dougherty doughera@lafcol.lafayette.edu .
+Original author: Andy Dougherty doughera@lafayette.edu .
Additions by Chip Salzenberg chip@perl.com and
Tim Bunce Tim.Bunce@ig.co.uk .
https://perl5.git.perl.org / perl5.git / blobdiff