X-Git-Url: http://git.silcnet.org/gitweb/?p=silc.git;a=blobdiff_plain;f=apps%2Fautodist%2Fdoc%2Fautodist.texi;h=928432e43d25f0fbe69f301f426c93cb0d654548;hp=870cc91ff4539f042ff1c750fefd4bea85d9b557;hb=816a5b080c797c0db47b7b274a85646343c3466e;hpb=c257b555225193e54d85daf541d29578b3c93882 diff --git a/apps/autodist/doc/autodist.texi b/apps/autodist/doc/autodist.texi index 870cc91f..928432e4 100644 --- a/apps/autodist/doc/autodist.texi +++ b/apps/autodist/doc/autodist.texi @@ -349,7 +349,7 @@ AUTOMAKE="automake -a -c" The 'AUTOMAKE' specifies the location of the 'automake' tool. If Autodist should not run 'automake' this option may be removed or set to empty value. User need to then run it manually. By default, the -'-a' and '-c' options are given to 'automake' to add any missing required +'-a' and '-c' options are given to 'automake' to add any missing required files. @@ -427,7 +427,8 @@ and are ignored. The 'name' directive defines the name of the distribution. It is optional directive, and if omitted the distribution name will be the name of the -distfile. +distfile. The 'PACKAGE_NAME' define delivered by Autoconf will contain +this name string. Example: @example @@ -444,6 +445,8 @@ optional directive, and if omitted the distribution package name will be the name of the distribution, if defined, or if omitted, then the name of the distfile. If this directive is omitted then normal GNU convention is used to decide the package name, derived from the distribution name. +The 'PACKAGE_TARNAME' define delivered by Autoconf will contain this +package name string. Example: @example @@ -458,8 +461,8 @@ Will create distribution packages named, for example, as The 'bug-report' directive can be used to define the email address where the bug-reports for the distribution should be sent. The directive is -optional. The 'bug-report' email address will be set for the Autoconf -which will deliver it via AC_INIT macro. +optional. The 'PACKAGE_BUGREPORT' define delivered by Autoconf will +contain this bug report string. @section Directive: license @@ -513,8 +516,8 @@ If the new header file has fewer lines that the current header file, all of the lines from the current header will not be replaced. If the new header has fewer lines, empty lines must be added to it. If the new header file has more lines than the current header file, the extra lines will not appear -in the replaced header. Basic rule is to always make sure the header file -has equal amount of lines in them. +in the replaced header. Basic rule is to always make sure the header +files have equal amount of lines in them. Second limitation is in indentation of the header files. It is suggested, though not mandatory, that the header files have the same indentation as @@ -524,6 +527,16 @@ the header file should start the license text at the second character also. If same indentation is not used the appearance of the replaced header may not be perfect. While this is a cosmetic issue, one still to remember. +Third limitation is that the distribution cannot be partially re-licensed. +If the 'license-header' directive is used then all files that have the +specified header will be replaced with the new header. There are +currently two ways to not re-license a file; use different license header +in the file than one specified in 'license-header', or specify the file or +directory in 'noprocess' directive. Using 'noprocess' is not possible if +the file needs to be otherwise processed for the distribution. Future +versions of Autodist may provide a mechanism to re-license only part of +the distribution. + Example current header: @example --- Start example @@ -556,7 +569,7 @@ 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). -Note that, the current header must match exactly the header used in +Note that, the current header must match exactly the header used in files. Otherwise the replacement will not be complete. @@ -639,14 +652,14 @@ distribution. The following options are available. template @end example -When set, the distribution is a template distribution. Templates are -special distributions which cannot be prepared or packaged with Autodist. -Templates can only be inherited. Usually, templates are used to define a -common template distribution for other distributions. Templates may set -distdefs, undefines, includes and excludes. A large software project -could have several distributions that share a common base. In this case -defining the common base as a template distribution and then inheriting -that distribution makes it easier to manage the distfiles. +When set, the distribution is a template distribution. Templates are +special distributions which cannot be prepared or packaged with Autodist. +Templates can only be inherited. Usually, templates are used to define a +common template distribution for other distributions. Templates may set +distdefs, undefines, includes, excludes and noprocesses. A large software +project could have several distributions that share a common base. In +this case defining the common base as a template distribution and then +inheriting that distribution makes it easier to manage the distfiles. @example no-dist @@ -761,19 +774,22 @@ 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, a single directory or a regular expression that -will match several files and/or directories. If directory is specified -then all files inside the directory will not be processed. +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. Example: @example noprocess autodist.texi +noprocess apps/foo/* @end example -Autodist will not process 'autodist.texi' file. +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. -Note that, 'noprocess' directive cannot be used to disallow processing -of any file with '.ad' suffix. +Also note that, 'noprocess' directive cannot be used to disallow +processing of any file with '.ad' suffix. @section Directive: pre-hook [...] @@ -805,6 +821,39 @@ executes the script: distribution name, distribution version and package name of distribution. The script may use these arguments if it needs them. +@section Directive: pre-process-dist-hook [...] + +The 'pre-process-dist-hook' directive can be used define additional +scripts that will be run when Autodist has started distribution creation. +This directive is optional. One or more scripts may be defined in one +'pre-process-dist-hook' directive. Zero or more 'pre-process-dist-hook' +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. + + +@section Directive: post-process-dist-hook [...] + +The 'post-process-dist-hook' directive can be used define additional +scripts that will be run when Autodist has finished distribution +processing. This directive is optional. One or more scripts may be +defined in one 'post-process-dist-hook' directive. Zero or more +'post-process-dist-hook' directives may be set for distribution. The +'post-process-dist-hook' hook will be run immediately after the Autodist +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. + + @section Directive: pre-dist-hook [...] The 'pre-dist-hook' directive can be used define additional scripts that @@ -812,8 +861,8 @@ will be run when Autodist has started distribution creation. This directive is optional. One or more scripts may be defined in one 'pre-dist-hook' directive. Zero or more 'pre-dist-hook' directives may be set for distribution. The 'pre-dist-hook' hook will be run immediately after -the Autodist has created the distribution directory but has not yet -started any distribution processing. +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 @@ -824,12 +873,12 @@ script may use these arguments if it needs them. @section Directive: post-dist-hook [...] The 'post-dist-hook' directive can be used define additional scripts that -will be run when Autodist has finished distribution processing. This +will be run when Autodist has finished distribution creation. This directive is optional. One or more scripts may be defined in one 'post-dist-hook' directive. Zero or more 'post-dist-hook' directives may -be set for distribution. The 'post-dist-hook' hook will be run immediately -after the Autodist has finished processing the destination distribution -directory but has not yet created the distribution package. +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 @@ -837,6 +886,37 @@ name of distribution and destination distribution directory name. The script may use these arguments if it needs them. +@section Running hooks + +The Autodist runs the hooks in the following order: + +Preparing source tree for configuration and compilation: + +@example +<...Autodist started...> +pre-hook +<...preparation...> +post-hook +<...Autodist exits...> +@end example + +Creating distribution: + +@example +<...Autodist started...> +pre-dist-hook +<...distribution directory created...> +pre-process-dist-hook +<...processing all files, processing excludes and includes...> +post-process-dist-hook +<...creating distribution package...> +post-dist-hook +<...Autodist exits...> +@end example + +When creating distribution the 'pre-hook' and 'post-hook' are not run. + + @section Example distfile The following is a simple distfile example. The example assumes that the @@ -856,8 +936,8 @@ define SILC_DIST_IRSSI undef SILC_DIST_MPI exclude doc/draft* pre-hook scripts/client-pre-run -post-dist-hook scripts/client-post-dist-run -post-dist-hook scripts/client-post-dist-kludge +post-process-dist-hook scripts/client-post-process +post-dist-hook scripts/client-post-dist-bin @end example @menu @@ -969,6 +1049,9 @@ preparation. They will be processed when creating the distribution package. 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. + @menu * Distdefines:: Using distdefs in files @end menu @@ -995,7 +1078,7 @@ configuration and compilation (@pxref{Preparing source tree, , , , }). By default the distdefs are named '_DIST_XXX', where 'XXX' is the name of distdef. However, many projects will want to define their own prefix for distdefs in the 'autodist.conf' configuration file (@pxref{autodist.conf, , , , }). -In the following examples a prefix 'SILC' is used, hence the prefix for +In the following examples a prefix 'SILC' is used, hence the prefix for the distdefs are 'SILC_DIST_'. The basic format for the distdefs are as follows: @@ -1037,12 +1120,13 @@ a compiler friendly format, defined below, should be used. @end example Note that, only the format defined above is supported. Other more complex -use of the preprocessor directives such as using '&&' and '||' in the '#ifdef' -or '#ifndef' are not supported, and neither is '#elif'. Also note, that in -the compiler friendly format the name of the distdef in comments and the -use of '!' character in the '#else' branch of '#ifdef' are mandatory. Also -note, that the distdef conditionals must be placed at the start of the line, -they must not be indented. +use of the preprocessor directives such as using '&&' and '||' in the +'#ifdef' or '#ifndef' are not supported, and neither is '#elif'. Also +note, that the name of the distdef in '#else' and '#endif' directives in +non-source format and in source format inside C comments (/* */), and the +use of '!' character in the '#else' branch of '#ifdef'" are mandatory. +Also note, that the distdef conditionals must be placed at the start of +the line, they must not be indented. The following example shows the use of non-source format: @@ -1099,6 +1183,8 @@ The following example shows the use of source code format: #ifndef SILC_DIST_FOOBAR foobar_replacement(); + foobar_hack_init(); + foobar_init(); #else /* SILC_DIST_FOOBAR */ real_foobar(); #endif /* SILC_DIST_FOOBAR */ @@ -1115,21 +1201,21 @@ would be: real_foobar(); @end example -Even before processing the source files with Autodist, the preprocessor -will respect the preprocessor directives if the code use '#include' to -include the distdef header file created by the Autodist (see -'autodist.conf' (@pxref{autodist.conf, , , , })). When the distribution -is packaged (@pxref{Creating distribution, , , , }) the Autodist will -process the files, and will remove any line not defined to be included. +Even before processing the source files with Autodist, the preprocessor +will respect the preprocessor directives if the code use '#include' to +include the distdef header file created by the Autodist (see +'autodist.conf' (@pxref{autodist.conf, , , , })). When the distribution +is packaged (@pxref{Creating distribution, , , , }) the Autodist will +process the files, and will remove any line not defined to be included. The preprocessor directives will also be removed. -Because the software project includes the header file with '#include' the -distdef header file needs to be present in the distribution, unless it is +Because the software project includes the header file with '#include' the +distdef header file needs to be present in the distribution, unless it is placed inside some other '#ifdef' conditional. If the distribution is prepared but not compiled (it is packaged after preparation without -compilation) then including the distdef header in the source is not +compilation) then including the distdef header in the source is not necessary. Including it then in the distribution is not necessary either. - + The software project should not use the same name space that distdef conditionals use for other than distribution usage. The Autodist will process any line that uses the formats above and has the specified prefix @@ -1232,14 +1318,14 @@ not using Autodist, then you would do this by running perhaps 'aclocal', this process is performed by Autodist, and running these tools manually or using 'autogen.sh' script is not necessary. -By default the 'autodist.conf' (@pxref{autodist.conf, , , , }) has defined -the tools that will be run by the Autodist when preparing the source tree. -These are 'aclocal', 'autoheader', 'autoconf', 'automake' and -'libtoolize'. If you do not whish that Autodist runs some or any of these -tools automatically, do not set them in the 'autodist.conf'. You would -then need to run them manually. However, this is not recommended. If you -need to run additional preparation scripts you may set your scripts either -in the 'pre-hook' and/or 'post-hook' where you can run what ever +By default the 'autodist.conf' (@pxref{autodist.conf, , , , }) has defined +the tools that will be run by the Autodist when preparing the source tree. +These are 'aclocal', 'autoheader', 'autoconf', 'automake' and +'libtoolize'. If you do not wish that Autodist runs some or any of these +tools automatically, do not set them in the 'autodist.conf'. You would +then need to run them manually. However, this is not recommended. If you +need to run additional preparation scripts you may set your scripts either +in the 'pre-hook' and/or 'post-hook' where you can run what ever additional processing you may need to prepare your source tree. By default the Autodist creates a 'default' distribution when you @@ -1262,10 +1348,10 @@ distribution run Autodist without any arguments. The Autodist will prepare your source tree. After that you may run './configure' and continue to compile with 'make'. -If you do not whish to use the 'default' distribution, or you whish +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 distribution, or you are preparing to create a new distribution package, -you will need to run the Autodist with the distribution you whish to +you will need to run the Autodist with the distribution you wish to prepare. @example @@ -1275,6 +1361,8 @@ prepare. This prepares your source tree for 'example-distribution' of version '1.0.3'. After that you may run './configure' and continue to compile with 'make'. If the version is omitted the version will be '0.0'. +The 'PACKAGE_VERSION' define delivered by Autoconf will contain this +version. Note that, running Autodist for preparation merely prepares your source tree for the distribution, it does not create an actual distribution @@ -1288,7 +1376,7 @@ distribution. However, the source files, or any other file (except files ending with '.ad' suffix) are not processed by the Autodist. When compiling your sources the preprocessor, however, will respect your distdef -conditionals inside your source files if you include the distdef header +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 by the Autodist. Rest of the files in the distribution will be processed @@ -1297,6 +1385,12 @@ the distribution you have prepared will behave in your source tree exactly the same way as if it was already packaged with Autodist (providing that you remember to include the distdef header file in your code). +When preparing the source tree Autodist will create a file 'autodist.dist' +which will contain information on the prepared distribution. When +Creating the distribution that file will be read by the Autodist +automatically. That file should not be removed or the distribution +cannot be packaged. + @menu * Creating distribution:: Creating distribution with Autodist @end menu @@ -1309,18 +1403,18 @@ Before creating a new distribution package, you will need to prepare the source tree for the distribution you want to create. After preparing your source tree you will be ready to create a new distribution. The Autodist package provides a simple helper script 'makedist' that may -be used to create the distribution. However, if you whish, you may +be used to create the distribution. However, if you wish, you may run the Autodist yourself, as the 'makedist' will call Autodist anyway. -To create a new distribution for the distribution you have prepared for -run makedist. +To create a new distribution for the distribution you have prepared for, +run first './configure' and then 'makedist'. @example makedist @end example This will run the Autodist and create a new distribution package that -is archived with 'tar' and compressed with 'gzip'. If you whish to +is archived with 'tar' and compressed with 'gzip'. If you wish to create packages also compressed with 'bzip2', 'compress' and/or 'zip' you may give one or all of the following options: @@ -1332,16 +1426,11 @@ This example would create, in addition of 'tar.gz' package, also a 'tar.bz2', 'tar.Z' and '.zip' packages. Current version of Autodist does not support archiving with 'shar'. -If you whish to run additional processing for your distributions when -they are being packaged you may set 'pre-dist-hook' and/or 'post-dist-hook' -in your distribution file. Also note that any hooks provided by Automake -in Makefiles will be run in normal manner. - -For additional help, you may give: - -@example - makedist --help -@end example +If you wish to run additional processing for your distributions when they +are being packaged you may set 'pre-process-dist-hook', +'post-process-dist-hook, 'pre-dist-hook' and/or 'post-dist-hook' in your +distribution file. Also note that any hooks provided by Automake in +Makefiles will be run in normal manner. @node Examples @@ -1356,7 +1445,7 @@ For additional help, you may give: @section Single distribution tree example, start to finish Lets suppose you have a simple source tree with one application, -called 'foozbar' you whish to release. While you would probably suffice +called 'foozbar' you wish to release. While you would probably suffice using Autoconf and Automake features you may still use Autodist. First, you create the default 'distdir' into your software package: @@ -1367,7 +1456,7 @@ First, you create the default 'distdir' into your software package: Then, you create the 'configure.ad' file from your existing 'configure.ac' or 'configure.in' file. If you don't have configure script written yet, -please refer to the Autoconf manual. In the 'autodist.ad' you add as +please refer to the Autoconf manual. In the 'configure.ad' you add as first macro in the file: @example @@ -1387,7 +1476,7 @@ define _DIST_FOOZBAR This distribution file go into 'distdir/foozbar'. And there you go. You have succesfully integrated Autodist into your -source tree. If you need to do development and you whish to use the +source tree. If you need to do development and you wish to use the 'default' distribution for that, you should inherit the new 'foozbar' distribution in it. Add the following line in 'distdir/default': @@ -1442,7 +1531,7 @@ directory 'distdir': Then, you create the 'configure.ad' file from your existing 'configure.ac' or 'configure.in' file. If you don't have configure script written yet, -please refer to the Autoconf manual. In the 'autodist.ad' you add as +please refer to the Autoconf manual. In the 'configure.ad' you add as first macro in the file: @example @@ -1484,6 +1573,7 @@ undef _DIST_CRYPTO @example # Common template +option template define _DIST_DOC define _DIST_LIB define _DIST_MATH