Merged silc_1_1_branch to trunk.

[silc.git] / apps / autodist / doc / autodist.texi

diff --git a/apps/autodist/doc/autodist.texi b/apps/autodist/doc/autodist.texi
index 928432e43d25f0fbe69f301f426c93cb0d654548..aadb62fca86dad87e06d086aa9c9c8895298ef26 100644 (file)
--- 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
 * 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
 
 
 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
 * 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
 
 
 @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, , , , }).
 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
 
 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.
 
 
 files.  Otherwise the replacement will not be complete.
 
 

+@section Directive: prereq <version>
+
+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 <distfile>
 
 The Autodist provides inheritance of distributions.  The 'inherit'
 @section Directive: inherit <distfile>
 
 The Autodist provides inheritance of distributions.  The 'inherit'


@@ -581,13 +601,14 @@ into the distribution.  The <distfile> specifies the name of the
 inherited distribution.  If the distribution cannot be inherited Autodist
 will give an error.
 
 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
 
 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.
 
 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 <symbol>
 
 
 @section Directive: define <symbol>
 


@@ -769,26 +805,24 @@ This will exclude the file 'README' and anything that match 'doc/client*'.
 
 @section Directive: noprocess <filename> [...]
 
 
 @section Directive: noprocess <filename> [...]
 

-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 <filename>
-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 <filename> 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
 
 Example:
 @example
 noprocess autodist.texi

-noprocess apps/foo/*
+noprocess apps/foo/

 @end example
 
 @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.
 
 
 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, , , , }).
 
 '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 <filename> [...]
 
 
 @section Directive: post-hook <filename> [...]


@@ -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.
 
 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 <filename> [...]
 
 
 @section Directive: pre-process-dist-hook <filename> [...]


@@ -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.
 
 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 <filename> [...]
 
 
 @section Directive: post-process-dist-hook <filename> [...]


@@ -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.
 
 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 <filename> [...]
 
 
 @section Directive: pre-dist-hook <filename> [...]


@@ -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 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 <filename> [...]
 
 
 @section Directive: post-dist-hook <filename> [...]


@@ -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.
 
 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
 
 
 @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.
 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
 @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
 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
 
 @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
 
     .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.
 
 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
 
 @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.
 
 directory 'distdir', 'autodist.conf' configuration file and the
 default distribution 'default', then exits.
 

+@item -p
+@itemx --process <type> <src> <dst>
+Process file <src> into <dst> for distribution, <type> is 'makefile',
+'configure', 'non-source' or 'source' and defines the type of <src>,
+then exits.
+

 @item -m
 @itemx --makedist
 Creates and packages distribution
 @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.
 
 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
 @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.
 
 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
 
 @node Examples
 @chapter Examples


@@ -1569,6 +1680,7 @@ include doc/nomad
 define _DIST_NOMAD
 define _DIST_NOMAD_LIB
 undef _DIST_CRYPTO
 define _DIST_NOMAD
 define _DIST_NOMAD_LIB
 undef _DIST_CRYPTO

+pre-dist-hook nomad-pre-dist-hook

 @end example
 
 @example
 @end example
 
 @example


@@ -1682,11 +1794,18 @@ Then you continue with libfoozbar and Nomad:
 autodist libfoozbar 1.0.5
 makedist
 
 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
 
 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
 
 @page
 @contents