INSTALL documentation

The core has a pod file "INSTALL" that documents how to build and
install perl from the source. It is quite extensive and - if you'd
ask me - complete.

This file (and others) are NOT available on https://perldoc.perl.org/
NOR https://dev.perl.org so there is no online doc that show how to
configure or build perl other than browsing the source and find the
INSTALL file

Tony suggested to install it as perlinstall.pod. This might lead to
information being available on dev.perl.org and/or perldoc.perl.org
but I still see some information that is missing:

 - what is the meaning of the extension(s) in perl -v:

   This is perl 5, version 31, subversion 1 (v5.31.1 (v5.31.0-167-gfa068f6da2*))
   built for x86_64-linux-thread-multi-ld
                          ^^^^^^^^^^^^^^^
   built for x86_64-linux-thread-multi
                          ^^^^^^^^^^^^
   built for x86_64-linux

   built for x86_64-linux-ld
                         ^^^

   Where can people find that -ld means it is a longdouble build and
   that this extension is the consequence of Configure being invoked
   with -Duselongdouble ?

 - do we need a list of all supported options? Configure --help shows a
   short summary:

  -D : define symbol to have some value:
         -D symbol         symbol gets the value 'define'
         -D symbol=value   symbol gets the value 'value'
       common used examples (see INSTALL for more info):
         -Duse64bitint            use 64bit integers
         -Duse64bitall            use 64bit integers and pointers
         -Dusethreads             use thread support
         -Dinc_version_list=none  do not include older perl trees in @INC
         -DEBUGGING=none          DEBUGGING options
         -Dcc=gcc                 choose your compiler
         -Dprefix=/opt/perl5      choose your destination

   and note that -Duselongdouble (or -Dusequadmath) are not named. Both
   are documented in INSTALL, which is not readily available in online
   documentation

Suggestions:

1. Link INSTALL to pos/perlinstall.pod and pod/perlbuild.pod in the
   early fase of building perl, so the documentation is available

2. Add a section in the beginning of INSTALL that lists all predefined
   known -D arguments with links to the section in INSTALL that
   describes them

3. A new section, probably also in INSTALL, that will explain the
   extensions, which configure option was used and where to find the
   docs for their meaning

-- 
H.Merijn Brand  http://tux.nl   Perl Monger  http://amsterdam.pm.org/
using perl5.00307 .. 5.31      porting perl5 on HP-UX, AIX, and Linux
https://useplaintext.email  https://tux.nl  http://www.test-smoke.org
http://qa.perl.org   http://www.goldmark.org/jeff/stupid-disclaimers/

• INSTALL documentation by H.Merijn Brand