X-Git-Url: https://perl5.git.perl.org/metaconfig.git/blobdiff_plain/0a071d90d27f35700f941a905b60bc5c0948b5c0..a4702bc3a3a1d20260ec20391fabf62f42644875:/README diff --git a/README b/README index dc0a0dc..660a907 100644 --- a/README +++ b/README @@ -35,8 +35,6 @@ Contents of this directory: 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 @@ -45,6 +43,8 @@ Contents of this directory: 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 @@ -88,7 +88,7 @@ Contents of this directory: $ 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 @@ -144,8 +144,7 @@ Contents of this directory: 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 @@ -161,31 +160,48 @@ Contents of this directory: (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. @@ -238,6 +254,19 @@ Contents of this directory: (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).