README: This file.
U: Metaconfig units used for building Perl's Configure
- U.check: Sample directory used for testing new metaconfig units.
- see U.check/README for more information.
dist-git:
a git clone of "dist". Optionally present. See (a) below.
This is where dist/meta resides as of 2016-04-01
These may differ from dist-git, as upstream also moves
on and develops.
+Development workflow:
+
(a) In order to assemble Configure from its units, you need mlint/metaline and
mconfig/metaconfig from the "dist" package installed and available in your
$PATH. You can either use the version that comes with your OS (Debian ships
$ export MC5=/your/path/to/metaconfig
$ alias ml="perl $MC5/bin/mlint -O"
- $ alias mc="perl $MC5/bin/mconfig -m -O -X .metaconf-exclusions.txt"
+ $ alias mc="perl $MC5/bin/mconfig -m -O"
examples in the rest of this README will just refer to mlint and mconfig
as if they appear in your $PATH
string HAS_STRTOLD_L at the end of the comment. This can be removed once
the code base has actual uses of the unit.
-(f) "mconfig -m -O -X .metaconf-exclusions.txt" to regenerate Configure and
- config_h.SH
+(f) "mconfig -m -O" to regenerate Configure and config_h.SH
Make *sure* your mconfig is the correct one in your $PATH, as the mono-web
package will install /usr/bin/mconfig which will do something completely
(h) The messy semi-automated part is that the knowledge of the new symbol
needs to be propagated to non-Configure lands like Win32, WinCE, Netware,
- VMS, VOS, EPOC, ... see previous Configure changes to see which are these
+ VMS, VOS, ... see previous Configure changes to see which are these
heathen lands. Files to take care of are
{win32,wince,NetWare}/config_[hH]*, (Win32, WinCE, NetWare),
- configure.com (VMS), epoc/config.sh (EPOC). Depending on the kind of
- patch djgpp/config* might also need adjusting (for example when
- adding/changing the list of extensions)
+ configure.com (VMS). Depending on the kind of patch djgpp/config* might
+ also need adjusting (for example when adding/changing the list of
+ extensions)
Most can be checked and updated by a tool Nicholas provided:
- $ cd perl
- $ perl Porting/checkcfgvar.pl
+ $ cd perl
+ $ perl Porting/checkcfgvar.pl
+
+ and if it shows differences, use one of:
+
+ $ perl Porting/checkcfgvar.pl --regen --default=undef
+ $ perl Porting/checkcfgvar.pl --regen --default=define
- and if it shows differences,
+ based on the changes you made. For safety, probes should probably be
+ 'undef', whereas some other things unconditionally should default to
+ 'define'. For example, 'default_inc_excludes_dot' should be 'define'
+ except in very limited circumstances, because it closes a security hole.
- $ perl Porting/checkcfgvar.pl --regen --default=define
+ For Win32 the process is semi-automated. You have to have a Win32
+ machine to run dmake on to complete the process, but that can be done
+ later by someone with such access.
- (of course "define" can also be "undef" based on the changes you made
+ For VMS, ('configure.com'), it may be best to add the units as 'undef' and
+ let the VMS experts deal with them later. However, you can set them to
+ 'define' if they are non-tricky (such as being basic functions having
+ standard signatures across architectures), and are in the oldest release of
+ VMS that perl can be compiled on, which is 7.3-2. Appendix A of "HP C
+ Run-Time Library Reference Manual for OpenVMS Systems" gives you that
+ information. As of October 2017, the latest version online is available
+ at: http://h41379.www4.hpe.com/doc/84final/5763/5763profile.html
- For Win32 the process is semi-automated -- if you have a Win32
- machine to run dmake on
+ In configure.com, if there is an existing probe that is essentially the
+ same (except for the names) as the one you're adding, you can copy, paste,
+ and adjust to create a new one, but note that it's easy to run afoul of the
+ quoting rules in configure.com. New probed-for units likely will require
+ at least 2 groups of changes.
- For vms, ('configure.com'), you likely will have to hand-edit in the
- changes, using a similar unit as a starting point. There likely will be at
- least 2 groups of changes. Rerun the tool until you've fixed everything it
- finds.
+ Rerun checkcfgvar.pl until you've fixed everything it finds.
(i) Check if U/mkglossary (right near the top) points to where you keep
dist's standard metaconfig units as well as your perl-specific ones.
(n) When all patches are applied, tested and committed, and you are happy,
git push
-(o) Documentation on 'dist' may be found at these locations:
- https://github.com/rmanfredi/dist/blob/master/mcon/man/mconfig.SH
- https://manpages.debian.org/stretch/dist/metaconfig.1.en.html
+References:
+
+Documentation on 'dist' may be found at these locations:
+https://github.com/rmanfredi/dist/blob/master/mcon/man/mconfig.SH
+https://manpages.debian.org/stretch/dist/metaconfig.1.en.html
+
+Git tags:
+
+Tags are maintained in this git repository mapping the version of the
+units that were used for the Configure in a given release of perl,
+named simply after the version of perl in question (for example, at
+the time of writing the current stable release is 5.26.1). This provides
+a stable reference for downstreams wishing to import the metaconfig units
+into their own packaging. Therefore, at minimum tags for each stable
+release should be made (adding tags for development releases being an
+optional extra).