X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=apps%2Fautodist%2Fdoc%2Fautodist.texi;h=aadb62fca86dad87e06d086aa9c9c8895298ef26;hb=52e57c880aba9c5e89f59d962eb9af75670b76e0;hp=928432e43d25f0fbe69f301f426c93cb0d654548;hpb=816a5b080c797c0db47b7b274a85646343c3466e;p=silc.git diff --git a/apps/autodist/doc/autodist.texi b/apps/autodist/doc/autodist.texi index 928432e4..aadb62fc 100644 --- a/apps/autodist/doc/autodist.texi +++ b/apps/autodist/doc/autodist.texi @@ -80,6 +80,7 @@ Integrating Autodist * Makefile.ad files:: Makefile.ad for creating Makefile.am * Other .ad files:: Other files with .ad suffix * Distdefines:: Using distdefs in files +* Dependencies:: Autodist dependency support Invoking Autodist @@ -240,6 +241,7 @@ as they may not exist yet. * Makefile.ad files:: Makefile.ad for creating Makefile.am * Other .ad files:: Other files with .ad suffix * Distdefines:: Using distdefs in files +* Dependencies:: Autodist dependency support @end menu @@ -500,6 +502,10 @@ Will replace all appearances of the license header in 'license/BSD-header' file to the license header in 'license/GPL-header' in any file in the distribution. Note that, the header change will be performed when the distribution is packaged (@pxref{Creating distribution, , , , }). +The 'makedist.log' file created by Autodist during distribution packaging +will list all files that were not re-licensed. The log file can be used +to check that the distribution is re-licensed correctly, and fix any +possible mistakes. With 'license-header' directive you may initially set your files in the source tree into what ever license you prefer. However, if you need to @@ -573,6 +579,20 @@ Note that, the current header must match exactly the header used in files. Otherwise the replacement will not be complete. +@section Directive: prereq + +The 'prereq' may be used to enforce the Autodist version. If the Autodist +version used to process the distribution is older than the version +specified with 'prereq' the Autodist will fail. + +Example: +@example +prereq 1.3.2 +@end example + +Will require Autodist 1.3.2 or newer for this distribution. + + @section Directive: inherit The Autodist provides inheritance of distributions. The 'inherit' @@ -581,13 +601,14 @@ into the distribution. The specifies the name of the inherited distribution. If the distribution cannot be inherited Autodist will give an error. -The 'inherit' will inherit the following information from the distribution: -distdefs, undefines, includes, excludes and noprocess. Other information -will not be inherited. If the inherited distribution inherits other -distributions, they will also be inherited automatically. User should be -careful when inheriting distributions as it may be possible to create an -infinite recursion. The Autodist would allow for this and not detect this -error. Zero or more 'inherit' directives may be set for distribution. +The 'inherit' will inherit the following information from the +distribution: distdefs, undefines, includes, excludes and noprocesses. +Other information will not be inherited. If the inherited distribution +inherits other distributions, they will also be inherited automatically. +User should be careful when inheriting distributions as it may be possible +to create an infinite recursion. The Autodist would allow for this and +not detect this error. Zero or more 'inherit' directives may be set for +distribution. Example: @example @@ -600,6 +621,21 @@ Will inherit distributions 'common', 'client' and 'toolkit' into this distribution. All distdefs, undefines, includes, excludes and noprocesses from these distributions are now also part this distribution. +The distribution that is being prepared or packaged take precedence when +defining distdefs that were specificly undefined in the inherited +distribution. This means that if the inherited distribution specificly +undefines a distdefs but the inheriting distribution (one being prepared +or packaged) specificly defines it, the distdef will be defined. +Similarly, if the inherited distribution defines a distdef but the +inheriting distribution undefines it, the distdef will be undefined. +Note that, this precedence works only in the top distribution (the one +being prepared or packaged). If the inherited distribution inherits other +distributions, all distdefs (defined and specificly undefined) will be +inherited as is. This means that if one inherited distribution defines a +distdef that other inherited distribution distdef undefines, it will be +undefined. However, the top distribution can then override them if +needed. + @section Directive: define @@ -769,26 +805,24 @@ This will exclude the file 'README' and anything that match 'doc/client*'. @section Directive: noprocess [...] -The 'noprocess' directive can be used to tell Autodist specificly not to -process a file. The Autodist will not process the file during -preparation or during distribution packaging. This directive is optional. -One or more file can be specified in the 'noprocess' directive. Zero or -more 'noprocess' directives can be used in distribution. The -can be a single file or a regular expression that will match several files. -Note that, in current Autodist version 'noprocess' cannot be used to -specify directories. +The 'noprocess' directive can be used to tell Autodist specificly not to +process files or directories. The Autodist will not process the files +during distribution packaging. This directive is optional. One or more +files can be specified in the 'noprocess' directive. Zero or more +'noprocess' directives can be used in distribution. The can be +a single file, a single directory or a regular expression that will match +several files and/or directories. Example: @example noprocess autodist.texi -noprocess apps/foo/* +noprocess apps/foo/ @end example -Autodist will not process 'autodist.texi' file, and any file that match -'apps/foo/*'. Note that, any subdirectory under 'apps/foo/' will not -match, and will be processed. +Autodist will not process 'autodist.texi' file, and any files and +directories under 'apps/foo/'. -Also note that, 'noprocess' directive cannot be used to disallow +Note that, 'noprocess' directive cannot be used to disallow processing of any file with '.ad' suffix. @@ -801,9 +835,11 @@ Zero or more 'pre-hook' directives may be set for distribution. The 'pre-hook' hook will be run immediately after invoking Autodist to start preparing the source tree for configuration and compilation (@pxref{Preparing source tree, , , , }). -The scripts will get three (3) command line arguments when Autodist -executes the script: distribution name, distribution version and package -name of distribution. The script may use these arguments if it needs them. +The scripts will get at least three (3) command line arguments when +Autodist executes the script: distribution name, distribution version and +package name of distribution. The script may use these arguments if it +needs them. If user passed any extra parameters to autodist in the +command line they will also be passed to the script as last arguments. @section Directive: post-hook [...] @@ -816,9 +852,11 @@ Zero or more 'post-hook' directives may be set for distribution. The preparing the source three for configuration and compilation (@pxref{Preparing source tree, , , , }). The Autodist will exit after it has run the 'post-hook' scripts. -The scripts will get three (3) command line arguments when Autodist -executes the script: distribution name, distribution version and package -name of distribution. The script may use these arguments if it needs them. +The scripts will get at least three (3) command line arguments when +Autodist executes the script: distribution name, distribution version and +package name of distribution. The script may use these arguments if it +needs them. If user passed any extra parameters to autodist in the +command line they will also be passed to the script as last arguments. @section Directive: pre-process-dist-hook [...] @@ -831,10 +869,12 @@ directives may be set for distribution. The 'pre-process-dist-hook' hook will be run immediately after the Autodist has created the distribution directory but has not yet started any distribution processing. -The scripts will get four (4) command line arguments when Autodist -executes the script: distribution name, distribution version, package -name of distribution and destination distribution directory name. The -script may use these arguments if it needs them. +The scripts will get at least four (4) command line arguments when +Autodist executes the script: distribution name, distribution version, +package name of distribution and destination distribution directory name. +The script may use these arguments if it needs them. If user passed any +extra parameters to autodist in the command line they will also be passed +to the script as last arguments. @section Directive: post-process-dist-hook [...] @@ -848,10 +888,12 @@ defined in one 'post-process-dist-hook' directive. Zero or more has finished processing the destination distribution directory but has not yet created the distribution package. -The scripts will get four (4) command line arguments when Autodist -executes the script: distribution name, distribution version, package -name of distribution and destination distribution directory name. The -script may use these arguments if it needs them. +The scripts will get at least four (4) command line arguments when +Autodist executes the script: distribution name, distribution version, +package name of distribution and destination distribution directory name. +The script may use these arguments if it needs them. If user passed any +extra parameters to autodist in the command line they will also be passed +to the script as last arguments. @section Directive: pre-dist-hook [...] @@ -864,10 +906,12 @@ distribution. The 'pre-dist-hook' hook will be run immediately after the Autodist has started distribution creation, but has not yet created the distribution directory. This hook is run before 'pre-process-dist-hook'. -The scripts will get four (4) command line arguments when Autodist -executes the script: distribution name, distribution version, package -name of distribution and destination distribution directory name. The -script may use these arguments if it needs them. +The scripts will get at least four (4) command line arguments when +Autodist executes the script: distribution name, distribution version, +package name of distribution and destination distribution directory name. +The script may use these arguments if it needs them. If user passed any +extra parameters to autodist in the command line they will also be passed +to the script as last arguments. @section Directive: post-dist-hook [...] @@ -880,10 +924,12 @@ be set for distribution. The 'post-dist-hook' hook will be run immediately after the Autodist has finished creating the distribution package. This is the last hook Autodist runs. -The scripts will get four (4) command line arguments when Autodist -executes the script: distribution name, distribution version, package -name of distribution and destination distribution directory name. The -script may use these arguments if it needs them. +The scripts will get at least four (4) command line arguments when +Autodist executes the script: distribution name, distribution version, +package name of distribution and destination distribution directory name. +The script may use these arguments if it needs them. If user passed any +extra parameters to autodist in the command line they will also be passed +to the script as last arguments. @section Running hooks @@ -1002,7 +1048,21 @@ macro 'AC_OUTPUT'. This macro has no arguments. Note that, the 'configure.ad' fragments are not real full featured configure scripts. They must not use 'AD_INIT', 'AD_INCLUDE_CONFIGURE', 'AC_INIT' or any other initialization macros. +@end defmac + + +@defmac AD_DISABLE_DEPENDENCIES + +This macro is used to disable Autodist dependencies. If this macro is +used, then after editing 'Makefile.ad' and 'configure.ad' files the +Autodist must be run manually. When dependencies are enabled Autodist is +run automatically when source is compiled with 'make'. Dependencies make +the development easier. This macro has no arguments. +Note that, the dependencies are enabled only in the prepared source tree. +Depedencies are not delivered to distribution, as they would require the +presence of 'Makefile.ad' and 'configure.ad' files, which are not +delivered to distribution. @end defmac @menu @@ -1050,7 +1110,9 @@ If you need processed files during configuration or compilation then they need to have '.ad' suffix. Note that, the distdef format used in these files must be the non-source -format. +format, even if the file is source file. This is because the distdefs +are processed during source tree preparation, and the source file will +have all distdefs removed when it is compiled. @menu * Distdefines:: Using distdefs in files @@ -1240,8 +1302,40 @@ The following suffixes will be considered as source files by the Autodist: .hh @end example +Also, any file that has '.in' suffix with any of the above source file +suffixes, the format inside the file must follow the source code format. Using distdefs in any other file must follow the non-source format. +Example: +@example + .c.in + .h.in +@end example + +In this example, in both of the files the source code format is used. + + +@node Dependencies +@section Autodist dependency support + +Autodist support dependencies for 'Makefile.ad' and 'configure.ad' files. +When these files are edited, they are processed by Autodist automatically +when the source tree is compiled with 'make'. This makes development in +the source tree easier, when Autodist does not have to be run manually. +The dependencies can be disabled by using 'AD_DISABLE_DEPENDENCIES' macro +in the 'configure.ad' file. + +When editing 'configure.ad' fragments the modifcation is detected when the +source tree is compiled with 'make' from the top source directory. +Giving 'make' in a subdirectory will not detect a change in 'configure.ad' +fragment. + +Dependencies are present only in the prepared source tree. They are not +delivered to created distribution, as they depend on 'Makefile.ad' and +'configure.ad' files which are not present in the created distribution. +Autodist automatically removes the dependencies when the distribution is +created. + @node Invoking Autodist @chapter Invoking Autodist @@ -1282,6 +1376,12 @@ Initializes Autodist environment. Creates the default distribution directory 'distdir', 'autodist.conf' configuration file and the default distribution 'default', then exits. +@item -p +@itemx --process +Process file into for distribution, is 'makefile', +'configure', 'non-source' or 'source' and defines the type of , +then exits. + @item -m @itemx --makedist Creates and packages distribution @@ -1391,6 +1491,9 @@ Creating the distribution that file will be read by the Autodist automatically. That file should not be removed or the distribution cannot be packaged. +Autodist also created a log file, 'autodist.log', that will include +messages created by Autodist during preparation. + @menu * Creating distribution:: Creating distribution with Autodist @end menu @@ -1432,6 +1535,14 @@ are being packaged you may set 'pre-process-dist-hook', distribution file. Also note that any hooks provided by Automake in Makefiles will be run in normal manner. +When creating the distribution Autodist creates a log file, +'makedist.log', that will include messages created by Autodist. It is +suggested that this file is checked after distribution is created. For +example, when the 'license-header' directive is used to re-license the +distribution, the 'makedist.log' will include list of files that were not +re-licensed. The log file can be used to verify that the distribution was +re-licensed correctly, and fix any possible mistakes. + @node Examples @chapter Examples @@ -1569,6 +1680,7 @@ include doc/nomad define _DIST_NOMAD define _DIST_NOMAD_LIB undef _DIST_CRYPTO +pre-dist-hook nomad-pre-dist-hook @end example @example @@ -1682,11 +1794,18 @@ Then you continue with libfoozbar and Nomad: autodist libfoozbar 1.0.5 makedist -autodist nomad 2.0 +Nomad has also an RPM .spec file that you have written and a pre-dist-hook +that will replace the RPM release version with sed tool with the one you +give as extra parameter to autodist: + +autodist nomad 2.0 0.fc7 makedist @end example -The end results are: 'libfoozbar-1.0.5.tar.gz' and 'nomad-2.0.tar.gz'. +The end results are: 'libfoozbar-1.0.5.tar.gz' and 'nomad-2.0.tar.gz', and +the RPM will have a release version '0.fc7' when you compile the RPM. Any +extra parameter that you pass to autodist will be delivered to your hook +scripts. @page @contents