1 \input texinfo @c -*-texinfo-*-
3 @setfilename autodist.info
12 This manual is for SILC Autodist (version @value{VERSION},
13 @value{UPDATED}), a program which is used to manage and create source
16 Copyright @copyright{} 2004 - 2005 Pekka Riikonen, SILC Project
19 Permission is granted to copy, distribute and/or modify this document
20 under the terms of the @acronym{GNU} Free Documentation License,
21 Version 1.2 or any later version published by the Free Software
22 Foundation; with no Invariant Sections, with the Front-Cover texts
23 being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in
24 (a) below. A copy of the license is included in the section entitled
25 ``@acronym{GNU} Free Documentation License.''
27 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and
28 modify this @acronym{GNU} Manual, like @acronym{GNU} software. Copies
29 published by the Free Software Foundation raise funds for
30 @acronym{GNU} development.''
34 @dircategory Software development
36 * autodist: (autodist). Managing and creating source distributions.
39 @dircategory Individual utilities
41 * makedist: (autodist)Invoking makedist. Creating distribution
46 @subtitle For version @value{VERSION}, @value{UPDATED}
47 @author Pekka Riikonen
49 @vskip 0pt plus 1filll
55 @comment node-name, next, previous, up
61 * Introduction:: Purpose of Autodist
62 * Integrating Autodist:: Integrating Autodist into your project
63 * Invoking Autodist:: Running Autodist
64 * Examples:: Examples using Autodist
67 --- The Detailed Node Listing ---
71 * Motivation:: Reasons for using Autodist
75 * Creating distdir:: Creating distributions directory
76 * autodist.conf:: Configuring Autodist
77 * Creating new distribution:: Adding new distribution
78 * Distribution file format:: Detailed document for distfile format
79 * configure.ad files:: configure script for creating configure.ac
80 * Makefile.ad files:: Makefile.ad for creating Makefile.am
81 * Other .ad files:: Other files with .ad suffix
82 * Distdefines:: Using distdefs in files
83 * Dependencies:: Autodist dependency support
87 * Preparing source tree:: Preparing source tree with Autodist
88 * Creating distribution:: Creating distribution with Autodist
92 * Single distribution tree:: Single distribution example
93 * Multiple distribution tree:: Multiple distributions example
102 @chapter Introduction
104 The Autodist is a source distribution management system that allows
105 powerful mechanisms to define what is included in and excluded from a
106 distribution, and what license the distribution is released under. It is
107 also used to create the actual distribution source packages. Autodist
108 allows distribution management in file, directory and file content level.
109 Different distributions may include different portions of files, for
110 example, excluding certain features from certain distributions. It is
111 always guaranteed that anything not defined for the distribution, is
112 removed automatically (files, file content, directories), thus ensuring
113 that nothing is accidentally included in the distribution.
115 The Autodist creates 'Makefile.am' files from 'Makefile.ad' files and
116 'configure.ac' file from one or more 'configure.ad' files. Any other file
117 ending with '.ad' suffix will also be processed. The processed file will
118 have the '.ad' suffix removed (@pxref{Preparing source tree, , , , }).
119 Autodist also creates and packages the distribution using common GNU
120 distribution creation process, specificly `make dist'. Autodist, however,
121 controls this process and during packaging phase the Autodist processes
122 all files in the distribution (other than '*.ad' files, which has already
123 been processed earlier by Autodist). The resulted package is a processed
124 source distribution package, processed according to the rules specified
125 in the distribution file(s) (@pxref{Creating distribution, , , , }).
127 Any file in the source tree may use distdefs (distribution defines (@pxref{Distdefines, , , , })) which are defined in the distributions. When distribution
128 is packaged only the files, directories and file content that is either
129 outside of any distdef, or inside the defined distdefs will be included
130 in the distribution. Any other file, directory or content in the file
131 will be removed. It is guaranteed, if a file, a directory or a piece of
132 file content is not inside a defined distdef it will not be delivered to
135 Any file, 'Makefile.am', 'configure.ac', or source file processed with
136 Autodist is always compliant with the tools needed to process them. All
137 files can also be processed with the corresponding tools even before
138 processing them with Autodist. This makes it possible, for example, to
139 compile sources before they have been processed, and undefined lines
140 are removed. The distdefs are respected in source files by the
143 Autodist is not a binary packaging system. It is specificly used to
144 create source distributions. A binary packaging system, however can be
145 hooked to the distribution creation process, if needed.
148 * Motivation:: Reasons for using Autodist
153 @section Reasons for using Autodist
155 Autodist is closely related to the Autoconf and Automake tools, and
156 complements the features Autoconf and Automake provides. It is especially
157 targeted into circumstances where multiple distributions are created from
158 one source tree. The Autoconf and Automake environment is mainly designed
159 for one distribution (one application) per one source tree situations.
160 Autodist provides mechanisms to create all kinds of distributions that can
161 be created from one source tree. To be able to use Autodist, the Autoconf
162 and Automake must be installed into the system (@pxref{Integrating Autodist, , , , }).
163 Autoconf version must be at least 2.52g.
165 Small software projects usually do very well with Autoconf and Automake
166 and their distribution management features. Often these projects do not
167 need Autodist, though they can benefit from it. However, if your software
168 project is large, you need to create multiple distributions from one source
169 tree, you have complex licensing terms for different distributions, you
170 have different target users or customers that may require different
171 feature set or licenses in different distributions, you have need to
172 continue concurrent development in the main source tree and still be able
173 to create stable distributions, and/or you have need to control file
174 content in different distributions (to avoid distributing code or features
175 that aren't supposed to be distributed, or to avoid leaking information
176 to your competitors on what new features you are working on), then Autodist
177 is a tool you may find usefull.
179 The motivation behind Autodist stems from need to be able to create
180 multiple distributions from one large source tree in a precise and
181 controllable manner, and guarantee that anything that is not part of the
182 distribution is removed from the distribution. The Autoconf and Automake
183 provides mere basic control what is included in and excluded from
184 distributions and how the distributions are created. They also do not
185 provide mechanism to define different licensing conditions for different
186 distributions, or changing the license automatically for different user
187 or customer purposes. Many large software projects, companies and
188 corporations have commonly been using Autoconf and Automake tools, but
189 have had the need to create their own ad-hoc mechanisms to control
190 distribution creation. The Autodist attempts to provide a tool that any
191 size software project can effectively use to manage their distributions.
193 Without a tool like Autodist, large software projects usually has to be
194 split into separate source trees, which may not always be possible because
195 they may share large portions of common code (which may further make
196 concurrent development of the applications hard), or multiple Autoconf and
197 Automake environments (multiple configure scripts) needs to be created
198 in one source tree. In this case the source tree usually gets very
199 complicated and controlling what is compiled and what is included in
200 distributions becomes harder, especially when different parts code is shared
201 between applications and libraries.
204 @node Integrating Autodist
205 @chapter Integrating Autodist
207 Integrating Autodist into existing software project can be a very simple
208 task or a fairly complicated task. It depends on the size and complexity
209 of the software project. Generally speaking, integrating Autodist into
210 software project is fairly straightforward process:
212 1. The distributions directory and 'default' distribution are created
214 2. The 'configure.ad' is created
216 3. If needed, 'Makefile.ad' file(s) are created
218 After this the Autodist can already be used to prepare the source tree
219 for configuration and compilation (@pxref{Preparing source tree, , , , }).
220 Adding a new distribution would then allow the actual distribution
223 If the software project has had own ad-hoc distribution system already in
224 place, it may take some work to move from that system into the Autodist.
225 If there are multiple applications and distributions created from the
226 source tree, the distributions and distribution defines for them need to
227 be created. While this may be unthankful job, it only needs to be done
230 Integrating Autodist into a new software project is a very simple task as
231 renaming 'configure.ac' and possibly 'Makefile.am' files are not required,
232 as they may not exist yet.
236 * Creating distdir:: Creating distributions directory
237 * autodist.conf:: Configuring Autodist
238 * Creating new distribution:: Adding new distribution
239 * Distribution file format:: Detailed document for distfile format
240 * configure.ad files:: configure script for creating configure.ac
241 * Makefile.ad files:: Makefile.ad for creating Makefile.am
242 * Other .ad files:: Other files with .ad suffix
243 * Distdefines:: Using distdefs in files
244 * Dependencies:: Autodist dependency support
248 @node Creating distdir
249 @section Creating distributions directory
251 The distributions directory is 'distdir', which is expected to be
252 located in the root of the source tree. This directory will hold all
253 the distribution files, and the Autodist configuration file 'autodist.conf' (@pxref{autodist.conf, , , , }).
254 If this directory does not exist it can be created with the Autodist.
260 This will create the 'distdir' and copy the default 'autodist.conf'
261 configuration file and the 'default' distribution into the directory.
262 The 'default' distribution will be used by default by the Autodist
263 unless other distribution is specified.
265 After this the Autodist has effectively been integrated into the
266 software project. However, usually after this, one would create new
267 distributions, the 'configure.ad' and possibly 'Makefile.ad' file(s).
268 Without 'configure.ad' file a distribution package cannot be created.
269 However, even without 'configure.ad' file the source tree can be
270 prepared for configuration and compilation (@pxref{Preparing source tree, , , , }).
273 * autodist.conf:: Configuring Autodist
278 @section Configuring Autodist
280 After the Autodist has been integrated into the software by creating
281 the 'distdir', the 'autodist.conf' configuration file was added to the
282 'distdir' also. Usually software projects will want to modify some of
283 the 'autodist.conf' options, mainly specifying the distdef prefix.
285 The 'autodist.conf' is a text file. The following options are available
293 By default the distdef prefix is '_DIST_'. To add own software package
294 specific prefix the 'DISTPREFIX' can be defined.
301 Will set the distdef prefix as 'SILC_DIST_'.
305 DISTDEFS="distdefs.h"
308 The 'DISTDEFS' option specifies the file name of the distdef header file
309 which Autodist will create. The software project should '#include' the
310 header file in order for the preprocessor to respect the distdef
311 conditionals (@pxref{Distdefines, , , , }). By default the file name
312 is 'distdefs.h' and is created at the root of source tree. Other location
313 may be specified if needed.
317 DISTDEFS="include/distdefs.h"
325 The 'ACLOCAL' specifies the location of the 'aclocal' tool. If Autodist
326 should not run 'aclocal' this option may be removed or set to empty value.
327 User need to then run it manually.
331 AUTOHEADER="autoheader"
334 The 'AUTOHEADER' specifies the location of the 'autoheader' tool. If
335 Autodist should not run 'autoheader' this option may be removed or set
336 to empty value. User need to then run it manually.
342 The 'AUTOCONF' specifies the location of the 'autoconf' tool. If
343 Autodist should not run 'autoconf' this option may be removed or set
344 to empty value. User need to then run it manually.
348 AUTOMAKE="automake -a -c"
351 The 'AUTOMAKE' specifies the location of the 'automake' tool. If
352 Autodist should not run 'automake' this option may be removed or set
353 to empty value. User need to then run it manually. By default, the
354 '-a' and '-c' options are given to 'automake' to add any missing required
359 LIBTOOLIZE="libtoolize --automake -c"
362 The 'LIBTOOLIZE' specifies the location of the 'libtoolize' tool.
363 This option should be removed or ste to empty value if 'libtool' is not
364 used in the source tree.
371 The 'MAKE' specifies the location of the 'make' program. This option must
372 be set to valid value in order to create distributions.
376 * Creating new distribution:: Adding new distribution
380 @node Creating new distribution
381 @section Creating new distribution
383 After the Autodist has been integrated into the software project by
384 creating the 'distdir' and 'default' distribution, the source tree
385 can be prepared for configuration and compilation (@pxref{Preparing source tree, , , , }). However, the 'default' distribution should be used only as
386 a development distribution. Usually it is used to prepare the raw source
387 tree (such as a tree just checkout
388 from CVS) for configuration and compilation. By default, the 'default'
389 distribution cannot be packaged. However, if the software project is
390 small (one distribution), it may be convenient to edit the 'default'
391 distribution to be as the distribution that is packaged from the source
392 tree. In software project where multiple distributions are created using
393 the 'default' only as a development distribution is recommended. The
394 real distributions should be defined as separate distributions.
396 Creating a new distribution is a simple process. Each distribution
397 is placed in the 'distdir' and the file name of the distribution file is
398 used to reference to it. By default, the distribution name is the
399 file name of the distribution file. The actual distribution file is
400 a simple text file with various directives that define the distribution.
402 If the 'default' distribution is used as a development distribution it
403 might be desired to inherit some or all of the created distributions in
404 it, so that development becomes possible with the 'default' distribution.
405 Adding 'inherit' directive into the 'distdir/default' will inherit the
406 specified distribution.
410 * Distribution file format:: Detailed document for distfile format
414 @node Distribution file format
415 @section Distribution file format in detail
417 The distribution file, or distfile from now on, defines your distribution,
418 distribution defines, options, included and excluded files and
419 directories, license, and additional processing. Each distribution is
420 defined in a separate file and the distributions are referenced by
423 The distfile is a text file that contains various directives that define
424 the actual distribution. Lines starting with '#' are considered comments
428 @section Directive: name <name>
430 The 'name' directive defines the name of the distribution. It is optional
431 directive, and if omitted the distribution name will be the name of the
432 distfile. The 'PACKAGE_NAME' define delivered by Autoconf will contain
440 Will set your distribution name as 'Foo Application'.
443 @section Directive: package <package>
445 The 'package' directive defines the name of the distribution package. It is
446 optional directive, and if omitted the distribution package name will
447 be the name of the distribution, if defined, or if omitted, then the name
448 of the distfile. If this directive is omitted then normal GNU convention
449 is used to decide the package name, derived from the distribution name.
450 The 'PACKAGE_TARNAME' define delivered by Autoconf will contain this
458 Will create distribution packages named, for example, as
459 'foo-client-1.0.tar.gz'.
462 @section Directive: bug-report <email address>
464 The 'bug-report' directive can be used to define the email address where
465 the bug-reports for the distribution should be sent. The directive is
466 optional. The 'PACKAGE_BUGREPORT' define delivered by Autoconf will
467 contain this bug report string.
470 @section Directive: license <filename>
472 The 'license' directive can be used to define the license file for the
473 distribution. This directive is optional. The license file will be
474 copied into the distribution in the name 'COPYING'. If the 'COPYING'
475 file already exist it will be replaced.
482 Will include the file 'license/GPL' into the distribution in the file
486 @section Directive: license-header <current-license> <new-license>
488 The 'license-header' can be used to re-license your files into a new
489 license. This directive is optional. There may be zero or more
490 'license-header' directives in distribution. The 'license-header'
491 directive will compare the license header that usually appear at the
492 start of a file to the <current-license>. If it matches it will
493 be replaced with the <new-license>. The license header in the file
494 will be replaced and the file will have effectively been re-licensed.
498 license-header license/BSD-header license/GPL-header
501 Will replace all appearances of the license header in 'license/BSD-header'
502 file to the license header in 'license/GPL-header' in any file in the
503 distribution. Note that, the header change will be performed when
504 the distribution is packaged (@pxref{Creating distribution, , , , }).
505 The 'makedist.log' file created by Autodist during distribution packaging
506 will list all files that were not re-licensed. The log file can be used
507 to check that the distribution is re-licensed correctly, and fix any
510 With 'license-header' directive you may initially set your files in the
511 source tree into what ever license you prefer. However, if you need to
512 re-license parts of the source tree in certain distributions the
513 'license-header' will achieve this automatically. For example, suppose
514 one wants to create two different versions of a library distribution, with
515 different feature sets, in two different licenses.
517 There are several limitations in the current implementation of Autodist
518 with the 'license-header' directive:
520 First limitation is that the header files must have equal amount of lines.
521 If the new header file has fewer lines that the current header file, all
522 of the lines from the current header will not be replaced. If the new header
523 has fewer lines, empty lines must be added to it. If the new header file
524 has more lines than the current header file, the extra lines will not appear
525 in the replaced header. Basic rule is to always make sure the header
526 files have equal amount of lines in them.
528 Second limitation is in indentation of the header files. It is suggested,
529 though not mandatory, that the header files have the same indentation as
530 is commonly used in the source tree; if the license header text in a file
531 starts at the second character instead of at the start of the line, then
532 the header file should start the license text at the second character also.
533 If same indentation is not used the appearance of the replaced header
534 may not be perfect. While this is a cosmetic issue, one still to remember.
536 Third limitation is that the distribution cannot be partially re-licensed.
537 If the 'license-header' directive is used then all files that have the
538 specified header will be replaced with the new header. There are
539 currently two ways to not re-license a file; use different license header
540 in the file than one specified in 'license-header', or specify the file or
541 directory in 'noprocess' directive. Using 'noprocess' is not possible if
542 the file needs to be otherwise processed for the distribution. Future
543 versions of Autodist may provide a mechanism to re-license only part of
546 Example current header:
549 This program is free software; you can redistribute it and/or modify
550 it under the terms of the GNU General Public License as published by
551 the Free Software Foundation; version 2 of the License.
553 This program is distributed in the hope that it will be useful,
554 but WITHOUT ANY WARRANTY; without even the implied warranty of
555 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
556 GNU General Public License for more details.
565 Redistribution and use in source and binary forms, with or without
566 modification, are permitted provided that the conditions listed in the
567 COPYING file are met.
574 In this example, if the text in the current header file is found in any
575 file in the distribution it will be replaced with the new header file.
576 Notice that, both header files has same amount of lines (8 lines).
578 Note that, the current header must match exactly the header used in
579 files. Otherwise the replacement will not be complete.
582 @section Directive: inherit <distfile>
584 The Autodist provides inheritance of distributions. The 'inherit'
585 directive is used to define the distribution which will be inherited
586 into the distribution. The <distfile> specifies the name of the
587 inherited distribution. If the distribution cannot be inherited Autodist
590 The 'inherit' will inherit the following information from the
591 distribution: distdefs, undefines, includes, excludes and noprocesses.
592 Other information will not be inherited. If the inherited distribution
593 inherits other distributions, they will also be inherited automatically.
594 User should be careful when inheriting distributions as it may be possible
595 to create an infinite recursion. The Autodist would allow for this and
596 not detect this error. Zero or more 'inherit' directives may be set for
606 Will inherit distributions 'common', 'client' and 'toolkit' into this
607 distribution. All distdefs, undefines, includes, excludes and noprocesses
608 from these distributions are now also part this distribution.
610 The distribution that is being prepared or packaged take precedence when
611 defining distdefs that were specificly undefined in the inherited
612 distribution. This means that if the inherited distribution specificly
613 undefines a distdefs but the inheriting distribution (one being prepared
614 or packaged) specificly defines it, the distdef will be defined.
615 Similarly, if the inherited distribution defines a distdef but the
616 inheriting distribution undefines it, the distdef will be undefined.
617 Note that, this precedence works only in the top distribution (the one
618 being prepared or packaged). If the inherited distribution inherits other
619 distributions, all distdefs (defined and specificly undefined) will be
620 inherited as is. This means that if one inherited distribution defines a
621 distdef that other inherited distribution distdef undefines, it will be
622 undefined. However, the top distribution can then override them if
626 @section Directive: define <symbol>
628 The 'define' directive is used to define the distdef symbols for the
629 distribution. This directive is optional, however, all distributions
630 should define at least one distdef so that the distribution may be
631 controlled with the distdef conditionals in files in the source tree (@pxref{Distdefines, , , , }). By default, the distdef prefix is '_DIST_'. Many
632 software projects will want to set their own prefix for the distdefs
633 for consistency. The prefix may be defined in the 'autodist.conf' file
634 (@pxref{autodist.conf, , , , }).
639 define _DIST_FEATURE_X
640 define _DIST_LIBRARY_Y
643 Will define the following distdefs for the distribution: '_DIST_FOO',
644 '_DIST_FEATURE_X' and '_DIST_LIBRARY_Y'. These distdefs may then be
645 used in the source tree and source code to control what is included in
646 or excluded from this distribution.
649 @section Directive: undef <symbol>
651 The 'undef' directive may be used to explicitly undefine a distdef.
652 When inheriting distributions it may be desired to be able undefine
653 certain distdefs. This directive is optional.
657 undef _DIST_FEATURE_Y
660 Will undefine '_DIST_FEATURE_Y' distdef. This distdef will not be part
661 of this distribution anymore, even if it is defined in some inherited
665 @section Directive: option <option> [...]
667 The 'option' directive is used to define various options for the
668 distribution. The options can change the behavior of the distribution.
669 This directive is optional. One or more options may be defined in one
670 'option' directive. Zero or more 'option' directives may be set for
671 distribution. The following options are available.
677 When set, the distribution is a template distribution. Templates are
678 special distributions which cannot be prepared or packaged with Autodist.
679 Templates can only be inherited. Usually, templates are used to define a
680 common template distribution for other distributions. Templates may set
681 distdefs, undefines, includes, excludes and noprocesses. A large software
682 project could have several distributions that share a common base. In
683 this case defining the common base as a template distribution and then
684 inheriting that distribution makes it easier to manage the distfiles.
690 Distributions with the 'no-dist' option are similar to templates, except
691 that they can be prepared with Autodist, but they cannot be packaged.
692 These are usually used as a common development distribution, such as the
693 'default' distribution created with 'autodist -i'.
699 If this option is set to normal distributions or distributions with
700 'no-dist' option, the distribution cannot be inherited. For template
701 this option has no effect. If distribution with this option is inherited
702 the Autodist will give an error.
705 @section Directive: include <source> [<destination>]
707 The 'include' directive can be used to include files or directories into
708 the distribution. Sometimes it may be desired to specify included
709 files and directories in distribution instead of Makefile.am and
710 EXTRA_DIST, especially if there are many distributions that need to
711 include specific files and directories. While it would be possible
712 to define them in Makefile.ad and use distdef conditionals to define
713 which will be included in which distribution, if there are many different
714 distributions it may pollute the Makefile.ad unnecessarily.
716 This directive is optional. The <source> may be a single file, a single
717 directory or a regular expression which will match several files and/or
718 directories. The <destination> is optional. If it is omitted then
719 the <source> will be copied into the same location in the distribution.
720 If the <destination> is provided the <source> will be copied into the
725 include apps/foobar/README README
727 include lib/libfoobar lib/foobarlib
729 include scripts/foobar.sh foo.sh
732 Will include the file 'apps/foobar/README' into the top distribution
733 directory in the name 'README', the directory 'lib/libfoo' into same
734 location in distribution, the directory 'lib/libfoobar' into
735 'lib/foobarlib' changing the name of the directory into 'foobarlib',
736 the files and directories that match 'doc/foo*' into the same locations
737 in distribution, and finally the 'scripts/foobar.sh' into the top
738 distribution directory changing the name of the file into 'foo.sh'.
740 Note that, the 'include' directives will be processed by the Autodist
741 only when the distribution is packaged (@pxref{Creating distribution, , , , }). When preparing the source
742 tree for configuration and compilation (@pxref{Preparing source tree, , , , })
743 the 'include' directives are ignored. This is same behavior as with
744 Makefile.am's EXTRA_DIST.
746 If the included file or directory does not exist the Autodist will
747 give an error and stop the distribution creation. If the destination
748 file exist, it will be replaced with the included file. If the
749 destination directory already exists, the contents of the source
750 directory will be copied into the directory. Note that, the directory
751 will not be copied into the directory; if the <destination> is specified,
752 also the name of the <source> file or directory must be specified,
753 otherwise the 'include' will change the name into the one specified.
757 include lib/libfoo lib
760 In this example the 'lib/libfoo' will be included as 'lib'. If the 'lib'
761 already exists, this effectively copies the contents of the 'lib/libfoo'
762 into 'lib'. In order to include the directory with same name, the
763 name must be specified.
767 include lib/libfoo lib/libfoo
768 include lib/foobar new_lib/foobar
771 This will include the 'lib/libfoo' into 'lib/libfoo' in distribution,
772 and 'lib/foobar' into 'new_lib/foobar' in distribution.
775 @section Directive: exclude <filename> [...]
777 The 'exclude' directive can be used to exclude files and directories from
778 the distribution. This directive is optional. This directive is
779 processed before processing the 'include' directive. The <filename>
780 can be a single file, a single directory or a regular expression that
781 will match several files and/or directories.
789 This will exclude the file 'README' and anything that match 'doc/client*'.
792 @section Directive: noprocess <filename> [...]
794 The 'noprocess' directive can be used to tell Autodist specificly not to
795 process files or directories. The Autodist will not process the files
796 during distribution packaging. This directive is optional. One or more
797 files can be specified in the 'noprocess' directive. Zero or more
798 'noprocess' directives can be used in distribution. The <filename> can be
799 a single file, a single directory or a regular expression that will match
800 several files and/or directories.
804 noprocess autodist.texi
808 Autodist will not process 'autodist.texi' file, and any files and
809 directories under 'apps/foo/'.
811 Note that, 'noprocess' directive cannot be used to disallow
812 processing of any file with '.ad' suffix.
815 @section Directive: pre-hook <filename> [...]
817 The 'pre-hook' directive can be used define additional scripts that
818 will be run before the source tree is prepared. This directive is
819 optional. One or more scripts may be defined in one 'pre-hook' directive.
820 Zero or more 'pre-hook' directives may be set for distribution. The
821 'pre-hook' hook will be run immediately after invoking Autodist to start
822 preparing the source tree for configuration and compilation (@pxref{Preparing source tree, , , , }).
824 The scripts will get at least three (3) command line arguments when
825 Autodist executes the script: distribution name, distribution version and
826 package name of distribution. The script may use these arguments if it
827 needs them. If user passed any extra parameters to autodist in the
828 command line they will also be passed to the script as last arguments.
831 @section Directive: post-hook <filename> [...]
833 The 'post-hook' directive can be used define additional scripts that
834 will be run after the source tree is prepared. This directive is
835 optional. One or more scripts may be defined in one 'post-hook' directive.
836 Zero or more 'post-hook' directives may be set for distribution. The
837 'post-hook' hook will be run immediately after the Autodist has finished
838 preparing the source three for configuration and compilation (@pxref{Preparing source tree, , , , }). The Autodist will exit after it has run the
841 The scripts will get at least three (3) command line arguments when
842 Autodist executes the script: distribution name, distribution version and
843 package name of distribution. The script may use these arguments if it
844 needs them. If user passed any extra parameters to autodist in the
845 command line they will also be passed to the script as last arguments.
848 @section Directive: pre-process-dist-hook <filename> [...]
850 The 'pre-process-dist-hook' directive can be used define additional
851 scripts that will be run when Autodist has started distribution creation.
852 This directive is optional. One or more scripts may be defined in one
853 'pre-process-dist-hook' directive. Zero or more 'pre-process-dist-hook'
854 directives may be set for distribution. The 'pre-process-dist-hook' hook
855 will be run immediately after the Autodist has created the distribution
856 directory but has not yet started any distribution processing.
858 The scripts will get at least four (4) command line arguments when
859 Autodist executes the script: distribution name, distribution version,
860 package name of distribution and destination distribution directory name.
861 The script may use these arguments if it needs them. If user passed any
862 extra parameters to autodist in the command line they will also be passed
863 to the script as last arguments.
866 @section Directive: post-process-dist-hook <filename> [...]
868 The 'post-process-dist-hook' directive can be used define additional
869 scripts that will be run when Autodist has finished distribution
870 processing. This directive is optional. One or more scripts may be
871 defined in one 'post-process-dist-hook' directive. Zero or more
872 'post-process-dist-hook' directives may be set for distribution. The
873 'post-process-dist-hook' hook will be run immediately after the Autodist
874 has finished processing the destination distribution directory but has not
875 yet created the distribution package.
877 The scripts will get at least four (4) command line arguments when
878 Autodist executes the script: distribution name, distribution version,
879 package name of distribution and destination distribution directory name.
880 The script may use these arguments if it needs them. If user passed any
881 extra parameters to autodist in the command line they will also be passed
882 to the script as last arguments.
885 @section Directive: pre-dist-hook <filename> [...]
887 The 'pre-dist-hook' directive can be used define additional scripts that
888 will be run when Autodist has started distribution creation. This directive
889 is optional. One or more scripts may be defined in one 'pre-dist-hook'
890 directive. Zero or more 'pre-dist-hook' directives may be set for
891 distribution. The 'pre-dist-hook' hook will be run immediately after
892 the Autodist has started distribution creation, but has not yet created
893 the distribution directory. This hook is run before 'pre-process-dist-hook'.
895 The scripts will get at least four (4) command line arguments when
896 Autodist executes the script: distribution name, distribution version,
897 package name of distribution and destination distribution directory name.
898 The script may use these arguments if it needs them. If user passed any
899 extra parameters to autodist in the command line they will also be passed
900 to the script as last arguments.
903 @section Directive: post-dist-hook <filename> [...]
905 The 'post-dist-hook' directive can be used define additional scripts that
906 will be run when Autodist has finished distribution creation. This
907 directive is optional. One or more scripts may be defined in one
908 'post-dist-hook' directive. Zero or more 'post-dist-hook' directives may
909 be set for distribution. The 'post-dist-hook' hook will be run
910 immediately after the Autodist has finished creating the distribution
911 package. This is the last hook Autodist runs.
913 The scripts will get at least four (4) command line arguments when
914 Autodist executes the script: distribution name, distribution version,
915 package name of distribution and destination distribution directory name.
916 The script may use these arguments if it needs them. If user passed any
917 extra parameters to autodist in the command line they will also be passed
918 to the script as last arguments.
921 @section Running hooks
923 The Autodist runs the hooks in the following order:
925 Preparing source tree for configuration and compilation:
928 <...Autodist started...>
932 <...Autodist exits...>
935 Creating distribution:
938 <...Autodist started...>
940 <...distribution directory created...>
941 pre-process-dist-hook
942 <...processing all files, processing excludes and includes...>
943 post-process-dist-hook
944 <...creating distribution package...>
946 <...Autodist exits...>
949 When creating distribution the 'pre-hook' and 'post-hook' are not run.
952 @section Example distfile
954 The following is a simple distfile example. The example assumes that the
955 distdefs prefix is 'SILC'.
958 # SILC Client distribution
961 bug-report silc-client-bugs@@silcnet.org
963 inherit platform-unix
964 inherit platform-win32
965 define SILC_DIST_CLIENT
966 define SILC_DIST_CLIENTLIB
967 define SILC_DIST_IRSSI
970 pre-hook scripts/client-pre-run
971 post-process-dist-hook scripts/client-post-process
972 post-dist-hook scripts/client-post-dist-bin
976 * configure.ad files:: configure script for creating configure.ac
980 @node configure.ad files
981 @section configure.ad files
983 Autodist creates 'configure.ac' file from the 'configure.ad' file. The
984 'configure.ad' file is a rather normal 'configure.ac' except that it accepts
985 also Autodist macros. Autodist also supports configure script fragments,
986 also named as 'configure.ad'. Any 'configure.ad' file in the source tree
987 can be incorporated into the the top 'configure.ad' file. Sometimes it may
988 be useful to split a large configure script into smaller fragments.
989 Especially in multi distribution system where certain libraries or features
990 can be excluded from certain distributions it may be useful to handle
991 their configuration from a configure fragment. If the library is
992 excluded then also its configuration can be excluded.
994 If the software project already has a 'configure.ac' or 'configure.in'
995 file, the 'configure.ad' can be created by simply renaming the current
996 file to 'configure.ad'. In this case the current configure script
997 must be edited to support Autodist. This is done by replacing the
998 'AC_INIT' to 'AD_INIT'. After specifying the 'AD_INIT' as the first
999 macro in the 'configure.ad', the Autodist support has been fully
1000 integrated into the software project.
1002 If your software project is going to use configure fragments, then
1003 also Autodist macro 'AD_INCLUDE_CONFIGURE' must be used. Autodist will
1004 automatically combine the fragments with the top 'configure.ac' script.
1005 To exclude a 'configure.ad' fragment from a distribution use the distdef
1006 conditionals inside the 'configure.ad' fragment file. If the distdef is
1007 not defined the fragment will be excluded automatically.
1009 The following macros are available in current Autodist version.
1013 The 'AD_INIT' macro is used in place of Autoconf macro 'AC_INIT'. The
1014 'AD_INIT' must be the first macro in the 'configure.ad', just like the
1015 'AC_INIT' macro in 'configure.ac'. The AD_INIT macro is used to deliver
1016 the distribution names, distribution version, package name and bug-report
1017 email address to the 'configure.ac' file that Autodist will create.
1018 The 'AC_INIT' macro must not be used in 'configure.ad' file.
1020 This macro is mandatory and Autodist will exit with error if it is not
1021 specified in 'configure.ad'. This macro has no arguments.
1025 @defmac AD_INCLUDE_CONFIGURE
1027 This macro is used to tell Autodist that it should include any other
1028 'configure.ad' fragment that is found from the source tree into the
1029 top 'configure.ad' file. Note that, the 'configure.ad' fragments will
1030 be incorporated at the location where this macro is used in the
1031 'configure.ad'. Usually this macro is placed just before the Autoconf
1032 macro 'AC_OUTPUT'. This macro has no arguments.
1034 Note that, the 'configure.ad' fragments are not real full featured
1035 configure scripts. They must not use 'AD_INIT', 'AD_INCLUDE_CONFIGURE',
1036 'AC_INIT' or any other initialization macros.
1040 @defmac AD_DISABLE_DEPENDENCIES
1042 This macro is used to disable Autodist dependencies. If this macro is
1043 used, then after editing 'Makefile.ad' and 'configure.ad' files the
1044 Autodist must be run manually. When dependencies are enabled Autodist is
1045 run automatically when source is compiled with 'make'. Dependencies make
1046 the development easier. This macro has no arguments.
1048 Note that, the dependencies are enabled only in the prepared source tree.
1049 Depedencies are not delivered to distribution, as they would require the
1050 presence of 'Makefile.ad' and 'configure.ad' files, which are not
1051 delivered to distribution.
1055 * Makefile.ad files:: Makefile.ad for creating Makefile.am
1059 @node Makefile.ad files
1060 @section Makefile.ad files
1062 Autodist creates 'Makefile.am' files from 'Makefile.ad' files. A software
1063 project do not need to use 'Makefile.ad' files if there is no need to
1064 use distdef conditionals inside makefiles. Usually a multi distribution
1065 software project, however will need to define certain things to different
1066 distributions. In these cases 'Makefile.ad' file needs to be created.
1068 Even though it would be possible to use distdef conditionals also inside
1069 'Makefile.am' files, Autodist does not process 'Makefile.am' files when
1070 preparing the source tree for configuration and compilation (@pxref{Preparing source tree, , , , }). Thus, the prepared environment would not be
1071 identical to the created distribution package (when the 'Makefile.am'
1072 will be processed), and configuration and compilation would be inconsistent.
1073 Basic rule is, if you need distdefs (@pxref{Distdefines, , , , }) inside
1074 makefiles, put them inside 'Makefile.ad' file.
1078 * Other .ad files:: Other files with .ad suffix
1082 @node Other .ad files
1083 @section Other .ad files
1085 Any file in the source tree can have the '.ad' suffix appended. Autodist
1086 will process any file that has the suffix when the source tree is
1087 prepared for configuration and compilation (@pxref{Preparing source tree, , , , }). If the files have distdef conditionals the Autodist will process them.
1088 The files will have the '.ad' suffix removed.
1090 Basic rule is, if you need to process some file when preparing the
1091 source tree for configuration and compilation, add '.ad' suffix to it.
1092 Distdefs (@pxref{Distdefines, , , , }) can be used in any file in source
1093 tree but without '.ad' suffix Autodist will not process those files during
1094 preparation. They will be processed when creating the distribution package.
1095 If you need processed files during configuration or compilation then they
1096 need to have '.ad' suffix.
1098 Note that, the distdef format used in these files must be the non-source
1099 format, even if the file is source file. This is because the distdefs
1100 are processed during source tree preparation, and the source file will
1101 have all distdefs removed when it is compiled.
1104 * Distdefines:: Using distdefs in files
1109 @section Using distribution defines (distdefs)
1111 Distribution defines, or distdefs from now on, are used to define inside
1112 a file what will be included in the distribution. Distribution may define
1113 many different distdefs, for example, based on feature sets, platforms, or
1114 for other similar reasons. If distdef is not defined for the distribution
1115 but is used in a file, anything inside the distdef in that file will be
1116 removed when the distribution is packaged (@pxref{Creating distribution, , , , }). This guarantees that only the files, directories and file content
1117 (such as source code) that is supposed to be delivered with the distribution
1118 are delivered. Delivering files or code accidentally in the distribution
1121 All other files, except files ending with '.ad' suffix are processed for
1122 distdefs only when the distribution is packaged. Files ending with '.ad'
1123 suffix are processed for distdefs when preparing the source tree for
1124 configuration and compilation (@pxref{Preparing source tree, , , , }).
1126 By default the distdefs are named '_DIST_XXX', where 'XXX' is the name of
1127 distdef. However, many projects will want to define their own prefix
1128 for distdefs in the 'autodist.conf' configuration file (@pxref{autodist.conf, , , , }).
1129 In the following examples a prefix 'SILC' is used, hence the prefix for
1130 the distdefs are 'SILC_DIST_'.
1132 The basic format for the distdefs are as follows:
1135 #ifdef SILC_DIST_DEFINE
1136 #endif SILC_DIST_DEFINE
1138 #ifndef SILC_DIST_DEFINE
1139 #endif SILC_DIST_DEFINE
1141 #ifdef SILC_DIST_DEFINE
1142 #else !SILC_DIST_DEFINE
1143 #endif SILC_DIST_DEFINE
1145 #ifndef SILC_DIST_DEFINE
1146 #else SILC_DIST_DEFINE
1147 #endif SILC_DIST_DEFINE
1150 This format should be used only in non-source files, as for example C and
1151 C++ compilers will not like this format inside a file. In source files
1152 a compiler friendly format, defined below, should be used.
1155 #ifdef SILC_DIST_DEFINE
1156 #endif /* SILC_DIST_DEFINE */
1158 #ifndef SILC_DIST_DEFINE
1159 #endif /* SILC_DIST_DEFINE */
1161 #ifdef SILC_DIST_DEFINE
1162 #else /* !SILC_DIST_DEFINE */
1163 #endif /* SILC_DIST_DEFINE */
1165 #ifndef SILC_DIST_DEFINE
1166 #else /* SILC_DIST_DEFINE */
1167 #endif /* SILC_DIST_DEFINE */
1170 Note that, only the format defined above is supported. Other more complex
1171 use of the preprocessor directives such as using '&&' and '||' in the
1172 '#ifdef' or '#ifndef' are not supported, and neither is '#elif'. Also
1173 note, that the name of the distdef in '#else' and '#endif' directives in
1174 non-source format and in source format inside C comments (/* */), and the
1175 use of '!' character in the '#else' branch of '#ifdef'" are mandatory.
1176 Also note, that the distdef conditionals must be placed at the start of
1177 the line, they must not be indented.
1179 The following example shows the use of non-source format:
1183 #ifdef SILC_DIST_SERVER
1186 #endif SILC_DIST_SERVER
1187 #ifndef SILC_DIST_CLIENT
1189 #endif SILC_DIST_CLIENT
1190 #ifdef SILC_DIST_TOOLKIT
1193 #else !SILC_DIST_TOOLKIT
1196 #ifdef SILC_DIST_CLIENT
1198 #endif SILC_DIST_CLIENT
1199 #endif SILC_DIST_TOOLKIT
1202 Say, in this example, your distribution has the SILC_DIST_CLIENT and
1203 SILC_DIST_SERVER defined, but not the SILC_DIST_TOOLKIT, the end result
1215 The lines defined specificly for the SILC_DIST_TOOLKIT, which in our
1216 example was not defined, were removed. Also lines that specificly
1217 expected certain distdefs not to be defined ('#ifndef') were removed.
1218 (Note the last remaining '\' in example above would be removed by the
1219 Autodist automatically to avoid errors with Automake.)
1221 The following example shows the use of source code format:
1225 #ifdef SILC_DIST_MPI
1228 #else /* !SILC_DIST_MPI */
1230 #endif /* SILC_DIST_MPI */
1232 #ifndef SILC_DIST_FOOBAR
1233 foobar_replacement();
1236 #else /* SILC_DIST_FOOBAR */
1238 #endif /* SILC_DIST_FOOBAR */
1241 Say, you have both SILC_DIST_MPI and SILC_DIST_FOOBAR defined, the end result
1252 Even before processing the source files with Autodist, the preprocessor
1253 will respect the preprocessor directives if the code use '#include' to
1254 include the distdef header file created by the Autodist (see
1255 'autodist.conf' (@pxref{autodist.conf, , , , })). When the distribution
1256 is packaged (@pxref{Creating distribution, , , , }) the Autodist will
1257 process the files, and will remove any line not defined to be included.
1258 The preprocessor directives will also be removed.
1260 Because the software project includes the header file with '#include' the
1261 distdef header file needs to be present in the distribution, unless it is
1262 placed inside some other '#ifdef' conditional. If the distribution is
1263 prepared but not compiled (it is packaged after preparation without
1264 compilation) then including the distdef header in the source is not
1265 necessary. Including it then in the distribution is not necessary either.
1267 The software project should not use the same name space that distdef
1268 conditionals use for other than distribution usage. The Autodist will
1269 process any line that uses the formats above and has the specified prefix
1270 (eg. 'SILC_DIST_') in those lines. Using same prefix for other purposes
1271 will produce unexpected results and invalid distributions.
1273 The following suffixes will be considered as source files by the Autodist:
1291 Also, any file that has '.in' suffix with any of the above source file
1292 suffixes, the format inside the file must follow the source code format.
1293 Using distdefs in any other file must follow the non-source format.
1301 In this example, in both of the files the source code format is used.
1305 @section Autodist dependency support
1307 Autodist support dependencies for 'Makefile.ad' and 'configure.ad' files.
1308 When these files are edited, they are processed by Autodist automatically
1309 when the source tree is compiled with 'make'. This makes development in
1310 the source tree easier, when Autodist does not have to be run manually.
1311 The dependencies can be disabled by using 'AD_DISABLE_DEPENDENCIES' macro
1312 in the 'configure.ad' file.
1314 When editing 'configure.ad' fragments the modifcation is detected when the
1315 source tree is compiled with 'make' from the top source directory.
1316 Giving 'make' in a subdirectory will not detect a change in 'configure.ad'
1319 Dependencies are present only in the prepared source tree. They are not
1320 delivered to created distribution, as they depend on 'Makefile.ad' and
1321 'configure.ad' files which are not present in the created distribution.
1322 Autodist automatically removes the dependencies when the distribution is
1326 @node Invoking Autodist
1327 @chapter Invoking Autodist
1329 The Autodist has two basic functions:
1331 1. Preparing source tree for configuration and compilation (@pxref{Preparing source tree, , , , })
1333 2. Creating distribution packages (@pxref{Creating distribution, , , , })
1335 The 'autodist' accepts the following options:
1341 Prints the help for the Autodist and exits.
1345 Prints version number and exits.
1349 Verbosely report processing.
1352 @itemx --distdir <dir>
1353 Search distributions from <dir> instead of default 'distdir'.
1356 @itemx --distdefs [<dist>]
1357 Prints distribution defines of <dist> and exits.
1361 Initializes Autodist environment. Creates the default distribution
1362 directory 'distdir', 'autodist.conf' configuration file and the
1363 default distribution 'default', then exits.
1366 @itemx --process <type> <src> <dst>
1367 Process file <src> into <dst> for distribution, <type> is 'makefile',
1368 'configure', 'non-source' or 'source' and defines the type of <src>,
1373 Creates and packages distribution
1376 Create package compressed with gzip (default)
1379 Create also package compressed with bzip2
1382 Create also package compressed with compress
1385 Create also package compressed with zip
1391 * Preparing source tree:: Preparing source tree with Autodist
1392 * Creating distribution:: Creating distribution with Autodist
1396 @node Preparing source tree
1397 @section Preparing source tree for configuration and compilation
1399 Before distribution can be created from the source tree, the source tree
1400 must be prepared for configuration and compilation. If your project is
1401 not using Autodist, then you would do this by running perhaps 'aclocal',
1402 'autoconf', 'autoheader' and 'automake' tools manually, or you would run an
1403 'autogen.sh' script that prepares your raw source tree. With Autodist
1404 this process is performed by Autodist, and running these tools manually
1405 or using 'autogen.sh' script is not necessary.
1407 By default the 'autodist.conf' (@pxref{autodist.conf, , , , }) has defined
1408 the tools that will be run by the Autodist when preparing the source tree.
1409 These are 'aclocal', 'autoheader', 'autoconf', 'automake' and
1410 'libtoolize'. If you do not wish that Autodist runs some or any of these
1411 tools automatically, do not set them in the 'autodist.conf'. You would
1412 then need to run them manually. However, this is not recommended. If you
1413 need to run additional preparation scripts you may set your scripts either
1414 in the 'pre-hook' and/or 'post-hook' where you can run what ever
1415 additional processing you may need to prepare your source tree.
1417 By default the Autodist creates a 'default' distribution when you
1418 initialize your project by running 'autodist -i'. The 'default'
1419 distribution should be used when you are developing in your source
1420 tree. By default, the 'default' distribution cannot be packaged,
1421 however, if your project creates only one distribution you may find
1422 it more convenient to define your distribution inside the 'default'
1423 distribution and allow it to be packaged also. If your source tree
1424 will create multiple distributions, the 'default' should be used only
1425 as development distribution. You would use it when you, for example,
1426 checkout your source tree from CVS and prepare it for configuration
1427 and compilation. To prepare your source tree with the 'default'
1428 distribution run Autodist without any arguments.
1434 The Autodist will prepare your source tree. After that you may run
1435 './configure' and continue to compile with 'make'.
1437 If you do not wish to use the 'default' distribution, or you wish
1438 to do the development in a tree specificly prepared for some specific
1439 distribution, or you are preparing to create a new distribution package,
1440 you will need to run the Autodist with the distribution you wish to
1444 autodist example-distribution 1.0.3
1447 This prepares your source tree for 'example-distribution' of version
1448 '1.0.3'. After that you may run './configure' and continue to compile
1449 with 'make'. If the version is omitted the version will be '0.0'.
1450 The 'PACKAGE_VERSION' define delivered by Autoconf will contain this
1453 Note that, running Autodist for preparation merely prepares your source
1454 tree for the distribution, it does not create an actual distribution
1455 package. When preparing source tree for configuration and compilation
1456 the Autodist will process any file that ends with '.ad' suffix. It will
1457 process all 'configure.ad' and 'Makefile.ad' files for that distribution.
1458 When you run './configure' your tree will be configured for that
1459 distribution, and when you compile with 'make' it will compile for that
1462 However, the source files, or any other file (except files ending with
1463 '.ad' suffix) are not processed by the Autodist. When compiling
1464 your sources the preprocessor, however, will respect your distdef
1465 conditionals inside your source files if you '#include' the distdef header
1466 file. This way, even the compiled binaries will be compiled for that
1467 distribution, even though the source files has not yet been processed
1468 by the Autodist. Rest of the files in the distribution will be processed
1469 when you create the actual distribution package. It is guaranteed that
1470 the distribution you have prepared will behave in your source tree exactly
1471 the same way as if it was already packaged with Autodist (providing that
1472 you remember to include the distdef header file in your code).
1474 When preparing the source tree Autodist will create a file 'autodist.dist'
1475 which will contain information on the prepared distribution. When
1476 Creating the distribution that file will be read by the Autodist
1477 automatically. That file should not be removed or the distribution
1480 Autodist also created a log file, 'autodist.log', that will include
1481 messages created by Autodist during preparation.
1484 * Creating distribution:: Creating distribution with Autodist
1488 @node Creating distribution
1489 @section Creating distribution package(s)
1491 Before creating a new distribution package, you will need to prepare
1492 the source tree for the distribution you want to create. After preparing
1493 your source tree you will be ready to create a new distribution. The
1494 Autodist package provides a simple helper script 'makedist' that may
1495 be used to create the distribution. However, if you wish, you may
1496 run the Autodist yourself, as the 'makedist' will call Autodist anyway.
1498 To create a new distribution for the distribution you have prepared for,
1499 run first './configure' and then 'makedist'.
1505 This will run the Autodist and create a new distribution package that
1506 is archived with 'tar' and compressed with 'gzip'. If you wish to
1507 create packages also compressed with 'bzip2', 'compress' and/or 'zip'
1508 you may give one or all of the following options:
1511 makedist --bzip2 --compress --zip
1514 This example would create, in addition of 'tar.gz' package, also a
1515 'tar.bz2', 'tar.Z' and '.zip' packages. Current version of Autodist does
1516 not support archiving with 'shar'.
1518 If you wish to run additional processing for your distributions when they
1519 are being packaged you may set 'pre-process-dist-hook',
1520 'post-process-dist-hook, 'pre-dist-hook' and/or 'post-dist-hook' in your
1521 distribution file. Also note that any hooks provided by Automake in
1522 Makefiles will be run in normal manner.
1524 When creating the distribution Autodist creates a log file,
1525 'makedist.log', that will include messages created by Autodist. It is
1526 suggested that this file is checked after distribution is created. For
1527 example, when the 'license-header' directive is used to re-license the
1528 distribution, the 'makedist.log' will include list of files that were not
1529 re-licensed. The log file can be used to verify that the distribution was
1530 re-licensed correctly, and fix any possible mistakes.
1537 * Single distribution tree:: Single distribution example
1538 * Multiple distribution tree:: Multiple distributions example
1541 @node Single distribution tree
1542 @section Single distribution tree example, start to finish
1544 Lets suppose you have a simple source tree with one application,
1545 called 'foozbar' you wish to release. While you would probably suffice
1546 using Autoconf and Automake features you may still use Autodist.
1548 First, you create the default 'distdir' into your software package:
1554 Then, you create the 'configure.ad' file from your existing 'configure.ac'
1555 or 'configure.in' file. If you don't have configure script written yet,
1556 please refer to the Autoconf manual. In the 'configure.ad' you add as
1557 first macro in the file:
1563 Then, you create distribution file for your application:
1566 # Foozbar distribution
1569 bug-report foozbar-bugs@@foo.z.bar
1570 define _DIST_FOOZBAR
1573 This distribution file go into 'distdir/foozbar'.
1575 And there you go. You have succesfully integrated Autodist into your
1576 source tree. If you need to do development and you wish to use the
1577 'default' distribution for that, you should inherit the new 'foozbar'
1578 distribution in it. Add the following line in 'distdir/default':
1584 After that, you can prepare the source tree for configuration and
1585 compilation by giving:
1591 After this command you can give './configure' and 'make'.
1593 If you want to do development directly in a tree prepared for the
1594 'foozbar' distribution, or you are ready to start creating a new
1595 distribution package, you give:
1598 autodist foozbar 1.0
1601 After this command you can give './configure' and 'make'.
1603 To create the distribution package, you will give:
1609 The end result will be a 'foozbar-1.0.tar.gz' package.
1612 @node Multiple distribution tree
1613 @section Multiple distribution tree example, start to finish
1615 Lets suppose you have a source tree from which you create multiple
1616 distributions, say three. If you really have a such source tree you
1617 must have by now noticed the difficulty of maintaining such a source tree
1618 and problems with controlling the distributions. Maybe you have sufficed
1619 with Autoconf and Automake, or perhaps you have created your own scripts
1620 that carry out the kludges. No more, for Autodist is here.
1622 First, you integrate Autodist into your tree by creating the distributions
1623 directory 'distdir':
1629 Then, you create the 'configure.ad' file from your existing 'configure.ac'
1630 or 'configure.in' file. If you don't have configure script written yet,
1631 please refer to the Autoconf manual. In the 'configure.ad' you add as
1632 first macro in the file:
1638 You then continue with creating the distribution files for your three
1639 distributions. Let's name them 'foozbar', 'libfoozbar' and 'nomad'.
1640 We will also create a common template that all distributions inherit.
1643 # Foozbar distribution
1646 bug-report foozbar-bugs@@foo.z.bar
1648 define _DIST_FOOZBAR
1652 # libfoozbar distribution
1654 bug-report libfoozbar-bugs@@foo.z.bar
1656 define _DIST_LIBFOOZBAR
1660 # Nomad distribution
1662 package nomad-the-server
1663 bug-report nomad-bugs@@foo.z.bar
1667 define _DIST_NOMAD_LIB
1669 pre-dist-hook nomad-pre-dist-hook
1684 You put the distribution files in the 'distdir' directory. In addition
1685 you will be doing development in the source tree using the 'default'
1686 distribution, you will add the new distributions to the 'distdir/default':
1694 To prepare the source tree for configuration and compilation you would
1701 This will prepare your source tree for configuration and compilation. Since
1702 the 'default' distribution inherits all distributions your development
1703 source tree will have all of them included. If you do not want to do this
1704 then don't inherit them in the 'default', but run the autodist specificly
1705 for the distributions, for example:
1711 Since all the distributions inherit the 'common' distribution they get
1712 all the distdefs that the 'common' defines. In this example various distdefs
1713 has been defined. You would use them in your code and in your makefiles
1714 to control various things. For example, let's say the 'common' distdefs
1715 control what directories distributions have. An example 'Makefile.ad'
1728 Perhaps the 'Makefile.ad' in 'lib' subdirectory could define something
1740 #ifdef _DIST_NOMAD_LIB
1742 #endif _DIST_NOMAD_LIB
1743 #ifdef _DIST_LIBFOOZBAR
1745 #endif _DIST_LIBFOOZBAR
1748 Since the 'nomad' distribution undefined the '_DIST_CRYPTO' distdef it
1749 would not have the 'cryptolib' in its distribution. Clearly Nomad
1750 don't need it. In addition of using the distdefs just in the makefiles
1751 you may want to use them in the source code as well:
1757 /* Initialize math library */
1759 #endif /* _DIST_MATH */
1764 After an intensive development period you're ready to create new releases.
1765 Let's say you're going to release all distributions:
1767 First you release Foozbar 0.5.1:
1770 autodist foozbar 0.5.1
1774 The end result is two files: 'foozbar-0.5.1.tar.gz' and
1775 'foozbar-0.5.1.tar.bz2'.
1777 Then you continue with libfoozbar and Nomad:
1780 autodist libfoozbar 1.0.5
1783 Nomad has also an RPM .spec file that you have written and a pre-dist-hook
1784 that will replace the RPM release version with sed tool with the one you
1785 give as extra parameter to autodist:
1787 autodist nomad 2.0 0.fc7
1791 The end results are: 'libfoozbar-1.0.5.tar.gz' and 'nomad-2.0.tar.gz', and
1792 the RPM will have a release version '0.fc7' when you compile the RPM. Any
1793 extra parameter that you pass to autodist will be delivered to your hook