Make the executable slightly smaller by using PL_hexdigit in

[perl5.git] / INSTALL

diff --git a/INSTALL b/INSTALL
index 1b36454..43f28d5 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -966,7 +966,12 @@ answers (such as installation directories and the local perl contact
 person) in the Policy.sh file.  If you want to build perl on another
 system using the same policy defaults, simply copy the Policy.sh file
 to the new system and Configure will use it along with the appropriate
-hint file for your system.
+hint file for your system. This will work even if Policy.sh was
+generated for another version of Perl, or on a system with a
+different architecture and/or operating system. However, in such cases,
+you should review the contents of the file before using it: for
+example, your new target may not keep its man pages in the same place
+as the system on which the file was generated.
 
 Alternatively, if you wish to change some or all of those policy
 answers, you should
@@ -1020,7 +1025,21 @@ as usual, and Perl will be built in /tmp/perl/build/directory.
 
 You can run perl scripts under the perl debugger at any time with
 B<perl -d your_script>.  If, however, you want to debug perl itself,
-you probably want to do
+you probably want to have support for perl internal debugging code
+(activated by adding -DDEBUGGING to ccflags), and/or support for the
+system debugger by adding -g to optimize.
+
+       sh Configure -DDEBUGGING=<mode>
+
+For a more eye appealing call, -DEBUGGING is defined to be an alias
+for -DDEBUGGING. For both, the -U calls are also supported, in order
+to be able to overrule the hints or Policy.sh settings.
+
+=over 4
+
+=item -DEBUGGING=old
+
+Which is the default, and supports the old convention of
 
        sh Configure -Doptimize='-g'
 
@@ -1039,6 +1058,26 @@ L<"Propagating your changes to config.sh"> below.)
 You can actually specify -g and -DDEBUGGING independently, but usually
 it's convenient to have both.
 
+=over 4
+
+=item -DDEBUGGING
+
+=item -DEBUGGING
+
+=item -DEBUGGING=both
+
+Sets both -DDEBUGGING in the ccflags, and add -g to optimize.
+
+=item -DEBUGGING=-g
+
+Adds -g to optimize, but does not set -DDEBUGGING.
+
+=item -DEBUGGING=none
+
+Removes -g from optimize, and -DDEBUGGING from ccflags.
+
+=back
+
 If you are using a shared libperl, see the warnings about multiple
 versions of perl under L<Building a shared Perl library>.
 
@@ -1313,15 +1352,44 @@ instead.  You'll probably save yourself time in the long run.
 
 =item Hint files
 
-The perl distribution includes a number of system-specific hints files
-in the hints/ directory.  If one of them matches your system, Configure
-will offer to use that hint file.
+Hint files tell Configure about a number of things:
+
+=over 4
+
+=item o
+
+The peculiarities or conventions of particular platforms -- non-standard
+library locations and names, default installation locations for binaries,
+and so on.
+
+=item o
+
+The deficiencies of the platform -- for example, library functions that,
+although present, are too badly broken to be usable; or limits on
+resources that are generously available on most platforms.
+
+=item o
+
+How best to optimize for the platform, both in terms of binary size and/or
+speed, and for Perl feature support. Because of wide variations in the
+implementation of shared libraries and of threading, for example, Configure
+often needs hints in order to be able to use these features.
+
+=back
+
+The perl distribution includes many system-specific hints files
+in the hints/ directory. If one of them matches your system, Configure
+will offer to use that hint file. Unless you have a very good reason
+not to, you should accept its offer.
 
 Several of the hint files contain additional important information.
 If you have any problems, it is a good idea to read the relevant hint file
 for further information.  See hints/solaris_2.sh for an extensive example.
 More information about writing good hints is in the hints/README.hints
-file.
+file, which also explains hint files known as callback-units.
+
+Note that any hint file is read before any Policy file, meaning that
+Policy overrides hints -- see L</Site-wide Policy settings>.
 
 =item *** WHOA THERE!!! ***
 
@@ -1937,7 +2005,8 @@ has to be used is C<-Dusecrosscompile>.
    sh ./Configure -des -Dusecrosscompile -D...
 
 This will make the cpp symbol USE_CROSS_COMPILE and the %Config
-symbol C<usecrosscompile> available.
+symbol C<usecrosscompile> available, and C<xconfig.h> will be used
+for cross-compilation.
 
 During the Configure and build, certain helper scripts will be created
 into the Cross/ subdirectory.  The scripts are used to execute a
@@ -2606,7 +2675,7 @@ size about 1.9MB in its i386 version:
 A nice trick to find out the minimal set of Perl library files you will
 need to run a Perl program is
 
-   perl -e 'do "prog.pl"; END { print "$_\n" for sort keys %INC }' 
+   perl -e 'do "prog.pl"; END { print "$_\n" for sort keys %INC }'
 
 (this will not find libraries required in runtime, unfortunately, but
 it's a minimal set) and if you want to find out all the files you can