You have presumably obtained the metaconfig from the repository e.g.
- $ git clone github.com:perl5-metaconfig/metaconfig metaconfig
+ $ git clone git@github.com:Perl/metaconfig metaconfig
When working with metaconfig you will generally have two git checkouts
next to each other: (1) this metaconfig checkout; and (2) a checkout of
-the Perl 5 source code in which you will generate a new Configure
-script. In this README, we will refer to these directories as the
-'metaconfig' directory and the 'perl' directory.
+the Perl source code in which you will generate a new Configure script. In this
+README, we will refer to these directories as the 'metaconfig' directory and
+the 'perl' directory.
Since these two directories are normally next to each other, so ../perl
will get you to perl and ../perl/../metaconfig will get you back here.
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.
-(a) In order to assemble Configure from its units, you need mlint/metaline and
+Development workflow:
+
+(a) In order to assemble Configure from its units, you need mlint/metalint 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
it) or the versions that are included in this checkout: just add the full
name of this folder/bin to your $PATH. If you are not planning to analyse
differences of the current state with upstream dist, you can skip the rest
- op step (a) now.
+ of step (a) now.
If you also want to play with or compare to the original meta/dist, you
can checkout that too.
(aa) We have not yet arranged for metaconfig to use perl's versions of the
'units' by default so you need some housekeeping in the perl directory...
- Then add metaconfig/bin to your $PATH or create aliases like
+ Add metaconfig/bin to your $PATH or create aliases like
$ 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
ln -s MANIFEST MANIFEST.new
chmod +w Configure config_h.SH Porting/Glossary Porting/config*
-(c) Create a new file for the new unit as U/foo/d_bar.U
- ('foo' is one of the existing folders in U except for 'all'. It most
- likely will be 'perl', but it could also be 'modified', 'compline' or any
- other existing folder). Choose the best appropriate subdir of U. See
- U/README for a description of the various subdirectories.) You should
- choose the closest existing unit file as a starting point, and first copy
- it to the new file. For example, the unit for seeing if strtold_l() exists
- was created as U/threads/d_strtold_l.U, copied from perl/d_strtold.U, then
- adjusted. It goes under 'threads' because it is used only on threaded
- perls.
+(c) Create a new file for the unit as U/foo/d_bar.U
+ ('foo' is one of the existing folders in U except for 'all'. If you are
+ modifying a unit already in dist, simply copy the dist version to
+ 'modified' as a starting point. Otherwise, create a new file in one of the
+ other directories. It most likely will be 'perl', but it could also be
+ 'compline' or any other existing folder). Choose the best appropriate
+ subdir of U. See U/README for a description of the various subdirectories.
+ You should choose the closest existing unit file as a starting point, and
+ first copy it to the new file. For example, the unit for seeing if
+ strtold_l() exists was created as U/threads/d_strtold_l.U, copied from
+ perl/d_strtold.U, then adjusted. It goes under 'threads' because it is
+ used only on threaded perls.
(d) Run "mlint -O" to see nits: as opposed to lint, the gripings of mlint
are usually serious and need fixing
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).