'miniperl' not well documented

[p5pRT]

Migrated from rt.perl.org#132137 (status was 'open')

Searchable as RT132137$

[p5pRT]

From @jkeenan

I would have expected to be able to find a paragraph or two underneath
'pod/' describing the purpose and functionality of 'miniperl'.

As the attachment demonstrates, no such documentation exists.

Is that deliberate?

If not, could we add a paragraph about 'miniperl'?

Thank you very much.
Jim Keenan

[p5pRT]

From @jkeenan

Summary of my perl5 (revision 5 version 27 subversion 4) configuration​:
  Commit id​: e271727
  Platform​:
  osname=linux
  osvers=4.4.0-93-generic
  archname=x86_64-linux
  uname='linux zareason 4.4.0-93-generic #116-ubuntu smp fri aug 11 21​:17​:51 utc 2017 x86_64 x86_64 x86_64 gnulinux '
  config_args='-des -Dusedevel'
  hint=recommended
  useposix=true
  d_sigaction=define
  useithreads=undef
  usemultiplicity=undef
  use64bitint=define
  use64bitall=define
  uselongdouble=undef
  usemymalloc=n
  default_inc_excludes_dot=define
  bincompat5005=undef
  Compiler​:
  cc='cc'
  ccflags ='-fwrapv -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64'
  optimize='-O2'
  cppflags='-fwrapv -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include'
  ccversion=''
  gccversion='5.4.0 20160609'
  gccosandvers=''
  intsize=4
  longsize=8
  ptrsize=8
  doublesize=8
  byteorder=12345678
  doublekind=3
  d_longlong=define
  longlongsize=8
  d_longdbl=define
  longdblsize=16
  longdblkind=3
  ivtype='long'
  ivsize=8
  nvtype='double'
  nvsize=8
  Off_t='off_t'
  lseeksize=8
  alignbytes=8
  prototype=define
  Linker and Libraries​:
  ld='cc'
  ldflags =' -fstack-protector-strong -L/usr/local/lib'
  libpth=/usr/local/lib /usr/lib/gcc/x86_64-linux-gnu/5/include-fixed /usr/include/x86_64-linux-gnu /usr/lib /lib/x86_64-linux-gnu /lib/../lib /usr/lib/x86_64-linux-gnu /usr/lib/../lib /lib /lib64 /usr/lib64
  libs=-lpthread -lnsl -ldb -ldl -lm -lcrypt -lutil -lc
  perllibs=-lpthread -lnsl -ldl -lm -lcrypt -lutil -lc
  libc=libc-2.23.so
  so=so
  useshrplib=false
  libperl=libperl.a
  gnulibc_version='2.23'
  Dynamic Linking​:
  dlsrc=dl_dlopen.xs
  dlext=so
  d_dlsymun=undef
  ccdlflags='-Wl,-E'
  cccdlflags='-fPIC'
  lddlflags='-shared -O2 -L/usr/local/lib -fstack-protector-strong'

Characteristics of this binary (from libperl)​:
  Compile-time options​:
  HAS_TIMES
  PERLIO_LAYERS
  PERL_COPY_ON_WRITE
  PERL_DONT_CREATE_GVSV
  PERL_MALLOC_WRAP
  PERL_OP_PARENT
  PERL_PRESERVE_IVUV
  PERL_USE_DEVEL
  USE_64_BIT_ALL
  USE_64_BIT_INT
  USE_LARGE_FILES
  USE_LOCALE
  USE_LOCALE_COLLATE
  USE_LOCALE_CTYPE
  USE_LOCALE_NUMERIC
  USE_LOCALE_TIME
  USE_PERLIO
  USE_PERL_ATOF
  Built under linux
  Compiled at Sep 16 2017 10​:17​:33
  %ENV​:
  PERLBREW_BASHRC_VERSION="0.78"
  PERLBREW_HOME="/home/jkeenan/.perlbrew"
  PERLBREW_MANPATH="/home/jkeenan/perl5/perlbrew/perls/perl-5.26.0/man"
  PERLBREW_PATH="/home/jkeenan/perl5/perlbrew/bin​:/home/jkeenan/perl5/perlbrew/perls/perl-5.26.0/bin"
  PERLBREW_PERL="perl-5.26.0"
  PERLBREW_ROOT="/home/jkeenan/perl5/perlbrew"
  PERLBREW_VERSION="0.78"
  PERL_WORKDIR="/home/jkeenan/gitwork/perl"
  @​INC​:
  lib
  /usr/local/lib/perl5/site_perl/5.27.4/x86_64-linux
  /usr/local/lib/perl5/site_perl/5.27.4
  /usr/local/lib/perl5/5.27.4/x86_64-linux
  /usr/local/lib/perl5/5.27.4

[p5pRT]

From @jkeenan

pod/perlgit.pod​:720​:If you make any changes that affect miniperl or core routines that have
pod/perlgit.pod​:721​:different code paths for miniperl, be sure to run C<make minitest>.
pod/perlgit.pod-722-This will catch problems that even the full test suite will not catch
pod/perlgit.pod​:723​:because it runs a subset of tests under miniperl rather than perl.
pod/perlgit.pod-724-
--
pod/perl5260delta.pod​:2078​:F<Configure> now builds C<miniperl> and C<generate_uudmap> if you
pod/perl5260delta.pod-2079-invoke it with C<-Dusecrosscompiler> but not C<-Dtargethost=somehost>.
--
pod/Makefile.SH​:63​:PERL = ../miniperl
pod/Makefile.SH-64-PERLILIB = $(PERL) -I../lib
--
pod/perlinterp.pod​:28​:The action begins in F<perlmain.c>. (or F<miniperlmain.c> for miniperl)
pod/perlinterp.pod-29-This is very high-level code, enough to fit on a single screen, and it
--
pod/Makefile​:25​:PERL = ../miniperl
pod/Makefile-26-PERLILIB = $(PERL) -I../lib
--
pod/perl5123delta.pod​:46​:A separate DTrace is now build for miniperl, which means that perl can be
pod/perl5123delta.pod-47-compiled with -Dusedtrace on Solaris again.
--
pod/perl5180delta.pod​:2209​:with miniperl's C<glob> operator (which uses the C<perlglob> program)
pod/perl5180delta.pod-2210-deleting the PATH environment variable [perl #113798].
--
pod/perl5240delta.pod​:1190​:The Win32 miniperl now has a real C<getcwd> which increases build performance
pod/perl5240delta.pod​:1191​:resulting in C<getcwd()> being 605x faster in Win32 miniperl.
pod/perl5240delta.pod-1192-
--
pod/perl5240delta.pod​:1456​:During miniperl's process startup, during the build process, 4 to 8 IO calls
pod/perl5240delta.pod-1457-related to the process starting F<.pl> and the F<buildcustomize.pl> file were
--
pod/perl5220delta.pod​:2400​:Pathtools no longer tries to load XS on miniperl. This speeds up building perl
pod/perl5220delta.pod-2401-slightly.
--
pod/perl5220delta.pod​:2532​:F<miniperl.exe> is now built with C<-fno-strict-aliasing>, allowing 64-bit
pod/perl5220delta.pod-2533-builds to complete on GCC 4.8.
--
pod/perlhack.pod​:856​:Run F<miniperl> on F<t/base>, F<t/comp>, F<t/cmd>, F<t/run>, F<t/io>,
pod/perlhack.pod-857-F<t/op>, F<t/uni> and F<t/mro> tests.
--
pod/perlhack.pod​:1065​: cc -fstack-protector -L/usr/local/lib -o miniperl \
pod/perlhack.pod-1066- gv.o toke.o perly.o pad.o regcomp.o dump.o util.o \
--
pod/perlhack.pod​:1076​: makefile​:348​: recipe for target 'miniperl' failed
pod/perlhack.pod​:1077​: make​: *** [miniperl] Error 1
pod/perlhack.pod-1078-
--
pod/perlmodlib.PL​:1​:#!../miniperl
pod/perlmodlib.PL-2-
--
pod/perl5200delta.pod​:1913​:invocations of F<miniperl> are no longer made.
pod/perl5200delta.pod-1914-
--
pod/perl5200delta.pod​:1944​:We now build binaries for miniperl and generate_uudmap to be used on the host,
pod/perl5200delta.pod​:1945​:rather than running every miniperl call on the target; this means that, short
pod/perl5200delta.pod-1946-of 'make test', we no longer need access to the target system once Configure is
--
pod/perl5200delta.pod​:2192​:(for B<miniperl.exe> only).
pod/perl5200delta.pod-2193-[L<perl #121119|https://rt.perl.org/Public/Bug/Display.html?id=121119>]
--
pod/perl5200delta.pod​:2216​:When building a 64-bit perl, an uninitialized memory read in B<miniperl.exe>,
pod/perl5200delta.pod-2217-used during the build process, could lead to a 4GB B<wperl.exe> being created.
--
pod/perl5203delta.pod​:150​:B<miniperl.exe> is now built with B<-fno-strict-aliasing>, allowing 64-bit
pod/perl5203delta.pod-151-builds to complete with GCC 4.8.
--
pod/perl5120delta.pod​:470​:To support the bootstrapping process, F<miniperl> no longer builds with
pod/perl5120delta.pod-471-UTF-8 support in the regexp engine.
--
pod/perl5120delta.pod​:474​:Without this there's a bootstrapping problem, as miniperl can't load
pod/perl5120delta.pod-475-the UTF-8 components of the regexp engine, because they're not yet built.
--
pod/perl5120delta.pod​:479​:F<miniperl>'s @​INC is now restricted to just C<-I...>, the split of
pod/perl5120delta.pod-480-C<$ENV{PERL5LIB}>, and "C<.>"
--
pod/perl5120delta.pod​:1609​:issue with linking C<miniperl> has been fixed in the process.
pod/perl5120delta.pod-1610-
--
pod/perl5160delta.pod​:3031​:Under miniperl (used to configure modules when perl itself is built),
pod/perl5160delta.pod-3032-C<glob> now clears %ENV before calling csh, since the latter croaks on some
--
pod/perl58delta.pod​:2083​:VOS. The older methods, which build miniperl, are still
pod/perl58delta.pod-2084-available. See L<perlvos>. [561+]
--
pod/perl5161delta.pod​:55​:with miniperl's C<glob> operator (which uses the C<perlglob> program)
pod/perl5161delta.pod-56-deleting the PATH environment variable [perl #113798].

[p5pRT]

From @tonycoz

On Wed, 20 Sep 2017 15​:55​:44 -0700, jkeenan@​pobox.com wrote​:

I would have expected to be able to find a paragraph or two underneath
'pod/' describing the purpose and functionality of 'miniperl'.

As the attachment demonstrates, no such documentation exists.

Is that deliberate?

If not, could we add a paragraph about 'miniperl'?

If we described miniperl I'd think it would be part of perlhackbuild.pod or something similar describing the build process for perl, and how/where to back on it.

Tony

[p5pRT]

The RT System itself - Status changed from 'new' to 'open'

[jkeenan]

From @tonycoz

On Wed, 20 Sep 2017 15​:55​:44 -0700, jkeenan@​pobox.com wrote​:

I would have expected to be able to find a paragraph or two underneath
'pod/' describing the purpose and functionality of 'miniperl'.
As the attachment demonstrates, no such documentation exists.
Is that deliberate?
If not, could we add a paragraph about 'miniperl'?

If we described miniperl I'd think it would be part of perlhackbuild.pod or something similar describing the build process for perl, and how/where to back on it.

Tony

We have these 3 hacking-related POD files:

$ ls pod/perlhack* |cat
pod/perlhack.pod
pod/perlhacktips.pod
pod/perlhacktut.pod

We don't have a perlhackbuild.pod. Are you saying we should?

In any event, could we get a 1- or 2-paragraph description of the purpose and usage of miniperl -- regardless of where we stick it?

Thank you very much.
Jim Keenan

[tonycoz]

Something like:

F<miniperl> is a minimalistic perl built to bootstrap building extensions, utilties,
documentation etc.  It doesn't support dynamic loading and depending
on the point in the build process will only have access to a limited set of core
modules.  F<miniperl> is not intended for day to day use.

I still don't know where it belongs.

[khwilliamson]

+1 to the text

[jkeenan]

Also +1 to text. See p.r. #17538 or branch jkeenan/tonyc/ghi-16158/miniperl-doc.

Thank you very much.
Jim Keenan

[jkeenan]

Resolved by merge of #17538 into blead earlier today. Closing.