X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=apps%2Fautodist%2Fdoc%2Fautodist.texi;h=ce597b8344dd57b88f9fe8c9c1efff2b1622db6d;hb=5c255f0e6119860b4ba62731b006246fc25586ea;hp=e7542e367a87783bd8bf10d5937b6d96441a6e82;hpb=73c5a4691642f95d6f593b886d7d5dcf5ccd7466;p=autodist.git diff --git a/apps/autodist/doc/autodist.texi b/apps/autodist/doc/autodist.texi index e7542e3..ce597b8 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 @@ -116,7 +117,7 @@ The Autodist creates 'Makefile.am' files from 'Makefile.ad' files and ending with '.ad' suffix will also be processed. The processed file will have the '.ad' suffix removed (@pxref{Preparing source tree, , , , }). Autodist also creates and packages the distribution using common GNU -distribution creation process, specificly `make dist'. Autodist, however, +distribution creation process, specifically `make dist'. Autodist, however, controls this process and during packaging phase the Autodist processes all files in the distribution (other than '*.ad' files, which has already been processed earlier by Autodist). The resulted package is a processed @@ -139,7 +140,7 @@ compile sources before they have been processed, and undefined lines are removed. The distdefs are respected in source files by the preprocessor. -Autodist is not a binary packaging system. It is specificly used to +Autodist is not a binary packaging system. It is specifically used to create source distributions. A binary packaging system, however can be hooked to the distribution creation process, if needed. @@ -189,7 +190,7 @@ have had the need to create their own ad-hoc mechanisms to control distribution creation. The Autodist attempts to provide a tool that any size software project can effectively use to manage their distributions. -Without a tool like Autodist, large software projects usually has to be +Without a tool like Autodist, large software projects usually have to be split into separate source trees, which may not always be possible because they may share large portions of common code (which may further make concurrent development of the applications hard), or multiple Autoconf and @@ -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 @@ -571,12 +573,26 @@ Example new header: In this example, if the text in the current header file is found in any file in the distribution it will be replaced with the new header file. -Notice that, both header files has same amount of lines (8 lines). +Notice that, both header files have same amount of lines (8 lines). 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' @@ -606,15 +622,15 @@ 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 +defining distdefs that were specifically undefined in the inherited +distribution. This means that if the inherited distribution specifically undefines a distdefs but the inheriting distribution (one being prepared -or packaged) specificly defines it, the distdef will be defined. +or packaged) specifically 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 +distributions, all distdefs (defined and specifically 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 @@ -789,13 +805,13 @@ 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 +The 'noprocess' directive can be used to tell Autodist specifically not to process files or directories. The Autodist will not process the files -during preparation or 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. +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 @@ -806,7 +822,7 @@ noprocess apps/foo/ 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. @@ -819,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 [...] @@ -834,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 [...] @@ -849,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 [...] @@ -866,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 [...] @@ -882,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 [...] @@ -898,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 @@ -1020,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 @@ -1184,8 +1226,8 @@ SUBDIRS = \ client \ @end example -The lines defined specificly for the SILC_DIST_TOOLKIT, which in our -example was not defined, were removed. Also lines that specificly +The lines defined specifically for the SILC_DIST_TOOLKIT, which in our +example was not defined, were removed. Also lines that specifically expected certain distdefs not to be defined ('#ifndef') were removed. (Note the last remaining '\' in example above would be removed by the Autodist automatically to avoid errors with Automake.) @@ -1273,6 +1315,28 @@ 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 @@ -1312,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 @@ -1379,7 +1449,7 @@ The Autodist will prepare your source tree. After that you may run './configure' and continue to compile with 'make'. If you do not wish to use the 'default' distribution, or you wish -to do the development in a tree specificly prepared for some specific +to do the development in a tree specifically prepared for some specific distribution, or you are preparing to create a new distribution package, you will need to run the Autodist with the distribution you wish to prepare. @@ -1408,7 +1478,7 @@ However, the source files, or any other file (except files ending with your sources the preprocessor, however, will respect your distdef conditionals inside your source files if you '#include' the distdef header file. This way, even the compiled binaries will be compiled for that -distribution, even though the source files has not yet been processed +distribution, even though the source files have not yet been processed by the Autodist. Rest of the files in the distribution will be processed when you create the actual distribution package. It is guaranteed that the distribution you have prepared will behave in your source tree exactly @@ -1610,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 @@ -1644,7 +1715,7 @@ autodist This will prepare your source tree for configuration and compilation. Since the 'default' distribution inherits all distributions your development source tree will have all of them included. If you do not want to do this -then don't inherit them in the 'default', but run the autodist specificly +then don't inherit them in the 'default', but run the autodist specifically for the distributions, for example: @example @@ -1653,7 +1724,7 @@ autodist foozbar Since all the distributions inherit the 'common' distribution they get all the distdefs that the 'common' defines. In this example various distdefs -has been defined. You would use them in your code and in your makefiles +have been defined. You would use them in your code and in your makefiles to control various things. For example, let's say the 'common' distdefs control what directories distributions have. An example 'Makefile.ad' file: @@ -1722,12 +1793,21 @@ Then you continue with libfoozbar and Nomad: @example autodist libfoozbar 1.0.5 makedist +@end example -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: + +@example +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