93f01beee37716992357b9fdfec1cdd9e77e50b6
[autodist.git] / apps / autodist / doc / autodist.texi
1 \input texinfo   @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename autodist.info
4 @settitle autodist
5 @setchapternewpage off
6 @c %**end of header
7
8 @include version.texi
9
10 @copying
11
12 This manual is for SILC Autodist (version @value{VERSION},
13 @value{UPDATED}), a program which is used to manage and create source
14 distributions.
15
16 Copyright @copyright{} 2004 - 2005 Pekka Riikonen, SILC Project
17
18 @quotation
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.''
26
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.''
31 @end quotation
32 @end copying
33
34 @dircategory Software development
35 @direntry
36 * autodist: (autodist).         Managing and creating source distributions.
37 @end direntry
38
39 @dircategory Individual utilities
40 @direntry
41 * makedist: (autodist)Invoking makedist.          Creating distribution
42 @end direntry
43
44 @titlepage
45 @title SILC Autodist
46 @subtitle For version @value{VERSION}, @value{UPDATED}
47 @author Pekka Riikonen
48 @page
49 @vskip 0pt plus 1filll
50 @insertcopying
51 @end titlepage
52
53 @ifnottex
54 @node Top
55 @comment  node-name,  next,  previous,  up
56 @top SILC Autodist
57
58 @insertcopying
59
60 @menu
61 * Introduction::                Purpose of Autodist
62 * Integrating Autodist::        Integrating Autodist into your project
63 * Invoking Autodist::           Running Autodist
64 * Examples::                    Examples using Autodist
65
66 @detailmenu
67  --- The Detailed Node Listing ---
68
69 Introduction
70
71 * Motivation::                  Reasons for using Autodist
72
73 Integrating Autodist
74
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
84 Invoking Autodist
85
86 * Preparing source tree::       Preparing source tree with Autodist
87 * Creating distribution::       Creating distribution with Autodist
88
89 Examples
90
91 * Single distribution tree::    Single distribution example
92 * Multiple distribution tree::  Multiple distributions example
93
94 @end detailmenu
95 @end menu
96
97 @end ifnottex
98
99
100 @node Introduction
101 @chapter Introduction
102
103 The Autodist is a source distribution management system that allows
104 powerful mechanisms to define what is included in and excluded from a
105 distribution, and what license the distribution is released under.  It is
106 also used to create the actual distribution source packages.  Autodist
107 allows distribution management in file, directory and file content level.
108 Different distributions may include different portions of files, for
109 example, excluding certain features from certain distributions.  It is
110 always guaranteed that anything not defined for the distribution, is
111 removed automatically (files, file content, directories), thus ensuring
112 that nothing is accidentally included in the distribution.
113
114 The Autodist creates 'Makefile.am' files from 'Makefile.ad' files and
115 'configure.ac' file from one or more 'configure.ad' files.  Any other file
116 ending with '.ad' suffix will also be processed.  The processed file will
117 have the '.ad' suffix removed (@pxref{Preparing source tree, , , , }).
118 Autodist also creates and packages the distribution using common GNU
119 distribution creation process, specificly `make dist'.  Autodist, however,
120 controls this process and during packaging phase the Autodist processes
121 all files in the distribution (other than '*.ad' files, which has already
122 been processed earlier by Autodist).  The resulted package is a processed
123 source distribution package, processed according to the rules specified
124 in the distribution file(s) (@pxref{Creating distribution, , , , }).
125
126 Any file in the source tree may use distdefs (distribution defines (@pxref{Distdefines, , , , })) which are defined in the distributions.  When distribution
127 is packaged only the files, directories and file content that is either
128 outside of any distdef, or inside the defined distdefs will be included
129 in the distribution.  Any other file, directory or content in the file
130 will be removed.  It is guaranteed, if a file, a directory or a piece of
131 file content is not inside a defined distdef it will not be delivered to
132 the distribution.
133
134 Any file, 'Makefile.am', 'configure.ac', or source file processed with
135 Autodist is always compliant with the tools needed to process them.  All
136 files can also be processed with the corresponding tools even before
137 processing them with Autodist.  This makes it possible, for example, to
138 compile sources before they have been processed, and undefined lines
139 are removed.  The distdefs are respected in source files by the
140 preprocessor.
141
142 Autodist is not a binary packaging system.  It is specificly used to
143 create source distributions.  A binary packaging system, however can be
144 hooked to the distribution creation process, if needed.
145
146 @menu
147 * Motivation::                  Reasons for using Autodist
148 @end menu
149
150
151 @node Motivation
152 @section Reasons for using Autodist
153
154 Autodist is closely related to the Autoconf and Automake tools, and
155 complements the features Autoconf and Automake provides.  It is especially
156 targeted into circumstances where multiple distributions are created from
157 one source tree.  The Autoconf and Automake environment is mainly designed
158 for one distribution (one application) per one source tree situations.
159 Autodist provides mechanisms to create all kinds of distributions that can
160 be created from one source tree.  To be able to use Autodist, the Autoconf
161 and Automake must be installed into the system (@pxref{Integrating Autodist, , , , }).
162 Autoconf version must be at least 2.52g.
163
164 Small software projects usually do very well with Autoconf and Automake
165 and their distribution management features.  Often these projects do not
166 need Autodist, though they can benefit from it.  However, if your software
167 project is large, you need to create multiple distributions from one source
168 tree, you have complex licensing terms for different distributions, you
169 have different target users or customers that may require different
170 feature set or licenses in different distributions, you have need to
171 continue concurrent development in the main source tree and still be able
172 to create stable distributions, and/or you have need to control file
173 content in different distributions (to avoid distributing code or features
174 that aren't supposed to be distributed, or to avoid leaking information
175 to your competitors on what new features you are working on), then Autodist
176 is a tool you may find usefull.
177
178 The motivation behind Autodist stems from need to be able to create
179 multiple distributions from one large source tree in a precise and
180 controllable manner, and guarantee that anything that is not part of the
181 distribution is removed from the distribution.  The Autoconf and Automake
182 provides mere basic control what is included in and excluded from
183 distributions and how the distributions are created.  They also do not
184 provide mechanism to define different licensing conditions for different
185 distributions, or changing the license automatically for different user
186 or customer purposes.  Many large software projects, companies and
187 corporations have commonly been using Autoconf and Automake tools, but
188 have had the need to create their own ad-hoc mechanisms to control
189 distribution creation.  The Autodist attempts to provide a tool that any
190 size software project can effectively use to manage their distributions.
191
192 Without a tool like Autodist, large software projects usually has to be
193 split into separate source trees, which may not always be possible because
194 they may share large portions of common code (which may further make
195 concurrent development of the applications hard), or multiple Autoconf and
196 Automake environments (multiple configure scripts) needs to be created
197 in one source tree.  In this case the source tree usually gets very
198 complicated and controlling what is compiled and what is included in
199 distributions becomes harder, especially when different parts code is shared
200 between applications and libraries.
201
202
203 @node Integrating Autodist
204 @chapter Integrating Autodist
205
206 Integrating Autodist into existing software project can be a very simple
207 task or a fairly complicated task.  It depends on the size and complexity
208 of the software project.  Generally speaking, integrating Autodist into
209 software project is fairly straightforward process:
210
211 1. The distributions directory and 'default' distribution are created
212
213 2. The 'configure.ad' is created
214
215 3. If needed, 'Makefile.ad' file(s) are created
216
217 After this the Autodist can already be used to prepare the source tree
218 for configuration and compilation (@pxref{Preparing source tree, , , , }).
219 Adding a new distribution would then allow the actual distribution
220 packaging also.
221
222 If the software project has had own ad-hoc distribution system already in
223 place, it may take some work to move from that system into the Autodist.
224 If there are multiple applications and distributions created from the
225 source tree, the distributions and distribution defines for them need to
226 be created.  While this may be unthankful job, it only needs to be done
227 once.
228
229 Integrating Autodist into a new software project is a very simple task as
230 renaming 'configure.ac' and possibly 'Makefile.am' files are not required,
231 as they may not exist yet.
232
233
234 @menu
235 * Creating distdir::            Creating distributions directory
236 * autodist.conf::               Configuring Autodist
237 * Creating new distribution::   Adding new distribution
238 * Distribution file format::    Detailed document for distfile format
239 * configure.ad files::          configure script for creating configure.ac
240 * Makefile.ad files::           Makefile.ad for creating Makefile.am
241 * Other .ad files::             Other files with .ad suffix
242 * Distdefines::                 Using distdefs in files
243 @end menu
244
245
246 @node Creating distdir
247 @section Creating distributions directory
248
249 The distributions directory is 'distdir', which is expected to be
250 located in the root of the source tree.  This directory will hold all
251 the distribution files, and the Autodist configuration file 'autodist.conf' (@pxref{autodist.conf, , , , }).
252 If this directory does not exist it can be created with the Autodist.
253
254 @example
255   autodist -i
256 @end example
257
258 This will create the 'distdir' and copy the default 'autodist.conf'
259 configuration file and the 'default' distribution into the directory.
260 The 'default' distribution will be used by default by the Autodist
261 unless other distribution is specified.
262
263 After this the Autodist has effectively been integrated into the
264 software project.  However, usually after this, one would create new
265 distributions, the 'configure.ad' and possibly 'Makefile.ad' file(s).
266 Without 'configure.ad' file a distribution package cannot be created.
267 However, even without 'configure.ad' file the source tree can be
268 prepared for configuration and compilation (@pxref{Preparing source tree, , , , }).
269
270 @menu
271 * autodist.conf::               Configuring Autodist
272 @end menu
273
274
275 @node autodist.conf
276 @section Configuring Autodist
277
278 After the Autodist has been integrated into the software by creating
279 the 'distdir', the 'autodist.conf' configuration file was added to the
280 'distdir' also.  Usually software projects will want to modify some of
281 the 'autodist.conf' options, mainly specifying the distdef prefix.
282
283 The 'autodist.conf' is a text file.  The following options are available
284 in 'autodist.conf':
285
286
287 @example
288 DISTPREFIX=""
289 @end example
290
291 By default the distdef prefix is '_DIST_'.  To add own software package
292 specific prefix the 'DISTPREFIX' can be defined.
293
294 Example:
295 @example
296 DISTPREFIX="SILC"
297 @end example
298
299 Will set the distdef prefix as 'SILC_DIST_'.
300
301
302 @example
303 DISTDEFS="distdefs.h"
304 @end example
305
306 The 'DISTDEFS' option specifies the file name of the distdef header file
307 which Autodist will create.  The software project should '#include' the
308 header file in order for the preprocessor to respect the distdef
309 conditionals (@pxref{Distdefines, , , , }).  By default the file name
310 is 'distdefs.h' and is created at the root of source tree.  Other location
311 may be specified if needed.
312
313 Example:
314 @example
315 DISTDEFS="include/distdefs.h"
316 @end example
317
318
319 @example
320 ACLOCAL="aclocal"
321 @end example
322
323 The 'ACLOCAL' specifies the location of the 'aclocal' tool.  If Autodist
324 should not run 'aclocal' this option may be removed or set to empty value.
325 User need to then run it manually.
326
327
328 @example
329 AUTOHEADER="autoheader"
330 @end example
331
332 The 'AUTOHEADER' specifies the location of the 'autoheader' tool.  If
333 Autodist should not run 'autoheader' this option may be removed or set
334 to empty value.  User need to then run it manually.
335
336 @example
337 AUTOCONF="autoconf"
338 @end example
339
340 The 'AUTOCONF' specifies the location of the 'autoconf' tool.  If
341 Autodist should not run 'autoconf' this option may be removed or set
342 to empty value.  User need to then run it manually.
343
344
345 @example
346 AUTOMAKE="automake -a -c"
347 @end example
348
349 The 'AUTOMAKE' specifies the location of the 'automake' tool.  If
350 Autodist should not run 'automake' this option may be removed or set
351 to empty value.  User need to then run it manually.  By default, the
352 '-a'  and '-c' options are given to 'automake' to add any missing required
353 files.
354
355
356 @example
357 LIBTOOLIZE="libtoolize --automake -c"
358 @end example
359
360 The 'LIBTOOLIZE' specifies the location of the 'libtoolize' tool.
361 This option should be removed or ste to empty value if 'libtool' is not
362 used in the source tree.
363
364
365 @example
366 MAKE=make
367 @end example
368
369 The 'MAKE' specifies the location of the 'make' program.  This option must
370 be set to valid value in order to create distributions.
371
372
373 @menu
374 * Creating new distribution::   Adding new distribution
375 @end menu
376
377
378 @node Creating new distribution
379 @section Creating new distribution
380
381 After the Autodist has been integrated into the software project by
382 creating the 'distdir' and 'default' distribution, the source tree
383 can be prepared for configuration and compilation (@pxref{Preparing source tree, , , , }).  However, the 'default' distribution should be used only as
384 a development distribution.  Usually it is used to prepare the raw source
385 tree (such as a tree just checkout
386 from CVS) for configuration and compilation.  By default, the 'default'
387 distribution cannot be packaged.  However, if the software project is
388 small (one distribution), it may be convenient to edit the 'default'
389 distribution to be as the distribution that is packaged from the source
390 tree.  In software project where multiple distributions are created using
391 the 'default' only as a development distribution is recommended.  The
392 real distributions should be defined as separate distributions.
393
394 Creating a new distribution is a simple process.  Each distribution
395 is placed in the 'distdir' and the file name of the distribution file is
396 used to reference to it.  By default, the distribution name is the
397 file name of the distribution file.  The actual distribution file is
398 a simple text file with various directives that define the distribution.
399
400 If the 'default' distribution is used as a development distribution it
401 might be desired to inherit some or all of the created distributions in
402 it, so that development becomes possible with the 'default' distribution.
403 Adding 'inherit' directive into the 'distdir/default' will inherit the
404 specified distribution.
405
406
407 @menu
408 * Distribution file format::    Detailed document for distfile format
409 @end menu
410
411
412 @node Distribution file format
413 @section Distribution file format in detail
414
415 The distribution file, or distfile from now on, defines your distribution,
416 distribution defines, options, included and excluded files and
417 directories, license, and additional processing.  Each distribution is
418 defined in a separate file and the distributions are referenced by
419 their file name.
420
421 The distfile is a text file that contains various directives that define
422 the actual distribution.  Lines starting with '#' are considered comments
423 and are ignored.
424
425
426 @section Directive: name <name>
427
428 The 'name' directive defines the name of the distribution.  It is optional
429 directive, and if omitted the distribution name will be the name of the
430 distfile.  The 'PACKAGE_NAME' define delivered by Autoconf will contain
431 this name string.
432
433 Example:
434 @example
435 name FOO Application
436 @end example
437
438 Will set your distribution name as 'Foo Application'.
439
440
441 @section Directive: package <package>
442
443 The 'package' directive defines the name of the distribution package.  It is
444 optional directive, and if omitted the distribution package name will
445 be the name of the distribution, if defined, or if omitted, then the name
446 of the distfile.  If this directive is omitted then normal GNU convention
447 is used to decide the package name, derived from the distribution name.
448 The 'PACKAGE_TARNAME' define delivered by Autoconf will contain this
449 package name string.
450
451 Example:
452 @example
453 package foo-client
454 @end example
455
456 Will create distribution packages named, for example, as
457 'foo-client-1.0.tar.gz'.
458
459
460 @section Directive: bug-report <email address>
461
462 The 'bug-report' directive can be used to define the email address where
463 the bug-reports for the distribution should be sent.  The directive is
464 optional.  The 'PACKAGE_BUGREPORT' define delivered by Autoconf will
465 contain this bug report string.
466
467
468 @section Directive: license <filename>
469
470 The 'license' directive can be used to define the license file for the
471 distribution.  This directive is optional.  The license file will be
472 copied into the distribution in the name 'COPYING'.  If the 'COPYING'
473 file already exist it will be replaced.
474
475 Example:
476 @example
477 license license/GPL
478 @end example
479
480 Will include the file 'license/GPL' into the distribution in the file
481 name 'COPYING'.
482
483
484 @section Directive: license-header <current-license> <new-license>
485
486 The 'license-header' can be used to re-license your files into a new
487 license.  This directive is optional.  There may be zero or more
488 'license-header' directives in distribution.  The 'license-header'
489 directive will compare the license header that usually appear at the
490 start of a file to the <current-license>.  If it matches it will
491 be replaced with the <new-license>.  The license header in the file
492 will be replaced and the file will have effectively been re-licensed.
493
494 Example:
495 @example
496 license-header license/BSD-header license/GPL-header
497 @end example
498
499 Will replace all appearances of the license header in 'license/BSD-header'
500 file to the license header in 'license/GPL-header' in any file in the
501 distribution.  Note that, the header change will be performed when
502 the distribution is packaged (@pxref{Creating distribution, , , , }).
503 The 'makedist.log' file created by Autodist during distribution packaging
504 will list all files that were not re-licensed.  The log file can be used
505 to check that the distribution is re-licensed correctly, and fix any
506 possible mistakes.
507
508 With 'license-header' directive you may initially set your files in the
509 source tree into what ever license you prefer.  However, if you need to
510 re-license parts of the source tree in certain distributions the
511 'license-header' will achieve this automatically.  For example, suppose
512 one wants to create two different versions of a library distribution, with
513 different feature sets, in two different licenses.
514
515 There are several limitations in the current implementation of Autodist
516 with the 'license-header' directive:
517
518 First limitation is that the header files must have equal amount of lines.
519 If the new header file has fewer lines that the current header file, all
520 of the lines from the current header will not be replaced.  If the new header
521 has fewer lines, empty lines must be added to it.  If the new header file
522 has more lines than the current header file, the extra lines will not appear
523 in the replaced header.  Basic rule is to always make sure the header 
524 files have equal amount of lines in them.
525
526 Second limitation is in indentation of the header files.  It is suggested,
527 though not mandatory, that the header files have the same indentation as
528 is commonly used in the source tree; if the license header text in a file
529 starts at the second character instead of at the start of the line, then
530 the header file should start the license text at the second character also.
531 If same indentation is not used the appearance of the replaced header
532 may not be perfect.  While this is a cosmetic issue, one still to remember.
533
534 Third limitation is that the distribution cannot be partially re-licensed.  
535 If the 'license-header' directive is used then all files that have the 
536 specified header will be replaced with the new header.  There are 
537 currently two ways to not re-license a file;  use different license header 
538 in the file than one specified in 'license-header', or specify the file or 
539 directory in 'noprocess' directive.  Using 'noprocess' is not possible if 
540 the file needs to be otherwise processed for the distribution.  Future 
541 versions of Autodist may provide a mechanism to re-license only part of 
542 the distribution.
543
544 Example current header:
545 @example
546 --- Start example
547   This program is free software; you can redistribute it and/or modify
548   it under the terms of the GNU General Public License as published by
549   the Free Software Foundation; version 2 of the License.
550
551   This program is distributed in the hope that it will be useful,
552   but WITHOUT ANY WARRANTY; without even the implied warranty of
553   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
554   GNU General Public License for more details.
555 --- end example
556 @end example
557
558 Example new header:
559 @example
560 --- Start example
561   All rights reserved.
562
563   Redistribution and use in source and binary forms, with or without
564   modification, are permitted provided that the conditions listed in the
565   COPYING file are met.
566
567
568
569 --- end example
570 @end example
571
572 In this example, if the text in the current header file is found in any
573 file in the distribution it will be replaced with the new header file.
574 Notice that, both header files has same amount of lines (8 lines).
575
576 Note that, the current header must match exactly the header used in
577 files.  Otherwise the replacement will not be complete.
578
579
580 @section Directive: inherit <distfile>
581
582 The Autodist provides inheritance of distributions.  The 'inherit'
583 directive is used to define the distribution which will be inherited
584 into the distribution.  The <distfile> specifies the name of the
585 inherited distribution.  If the distribution cannot be inherited Autodist
586 will give an error.
587
588 The 'inherit' will inherit the following information from the 
589 distribution: distdefs, undefines, includes, excludes and noprocesses.  
590 Other information will not be inherited.  If the inherited distribution 
591 inherits other distributions, they will also be inherited automatically.  
592 User should be careful when inheriting distributions as it may be possible 
593 to create an infinite recursion.  The Autodist would allow for this and 
594 not detect this error.  Zero or more 'inherit' directives may be set for 
595 distribution.
596
597 Example:
598 @example
599 inherit common
600 inherit client
601 inherit toolkit
602 @end example
603
604 Will inherit distributions 'common', 'client' and 'toolkit' into this
605 distribution.  All distdefs, undefines, includes, excludes and noprocesses
606 from these distributions are now also part this distribution.
607
608 The distribution that is being prepared or packaged take precedence when 
609 defining distdefs that were specificly undefined in the inherited 
610 distribution.  This means that if the inherited distribution specificly 
611 undefines a distdefs but the inheriting distribution (one being prepared 
612 or packaged) specificly defines it, the distdef will be defined.  
613 Similarly, if the inherited distribution defines a distdef but the 
614 inheriting distribution undefines it, the distdef will be undefined.  
615 Note that, this precedence works only in the top distribution (the one 
616 being prepared or packaged).  If the inherited distribution inherits other 
617 distributions, all distdefs (defined and specificly undefined) will be 
618 inherited as is.  This means that if one inherited distribution defines a 
619 distdef that other inherited distribution distdef undefines, it will be 
620 undefined.  However, the top distribution can then override them if 
621 needed.
622
623
624 @section Directive: define <symbol>
625
626 The 'define' directive is used to define the distdef symbols for the
627 distribution.  This directive is optional, however, all distributions
628 should define at least one distdef so that the distribution may be
629 controlled with the distdef conditionals in files in the source tree (@pxref{Distdefines, , , , }).  By default, the distdef prefix is '_DIST_'.  Many
630 software projects will want to set their own prefix for the distdefs
631 for consistency.  The prefix may be defined in the 'autodist.conf' file
632 (@pxref{autodist.conf, , , , }).
633
634 Example:
635 @example
636 define _DIST_FOO
637 define _DIST_FEATURE_X
638 define _DIST_LIBRARY_Y
639 @end example
640
641 Will define the following distdefs for the distribution: '_DIST_FOO',
642 '_DIST_FEATURE_X' and '_DIST_LIBRARY_Y'.  These distdefs may then be
643 used in the source tree and source code to control what is included in
644 or excluded from this distribution.
645
646
647 @section Directive: undef <symbol>
648
649 The 'undef' directive may be used to explicitly undefine a distdef.
650 When inheriting distributions it may be desired to be able undefine
651 certain distdefs.  This directive is optional.
652
653 Example:
654 @example
655 undef _DIST_FEATURE_Y
656 @end example
657
658 Will undefine '_DIST_FEATURE_Y' distdef.  This distdef will not be part
659 of this distribution anymore, even if it is defined in some inherited
660 distribution.
661
662
663 @section Directive: option <option> [...]
664
665 The 'option' directive is used to define various options for the
666 distribution.  The options can change the behavior of the distribution.
667 This directive is optional.  One or more options may be defined in one
668 'option' directive.  Zero or more 'option' directives may be set for
669 distribution.  The following options are available.
670
671 @example
672 template
673 @end example
674
675 When set, the distribution is a template distribution.  Templates are 
676 special distributions which cannot be prepared or packaged with Autodist. 
677 Templates can only be inherited.  Usually, templates are used to define a 
678 common template distribution for other distributions.  Templates may set 
679 distdefs, undefines, includes, excludes and noprocesses.  A large software 
680 project could have several distributions that share a common base.  In 
681 this case defining the common base as a template distribution and then 
682 inheriting that distribution makes it easier to manage the distfiles.
683
684 @example
685 no-dist
686 @end example
687
688 Distributions with the 'no-dist' option are similar to templates, except
689 that they can be prepared with Autodist, but they cannot be packaged.
690 These are usually used as a common development distribution, such as the
691 'default' distribution created with 'autodist -i'.
692
693 @example
694 no-inherit
695 @end example
696
697 If this option is set to normal distributions or distributions with
698 'no-dist' option, the distribution cannot be inherited.  For template
699 this option has no effect.  If distribution with this option is inherited
700 the Autodist will give an error.
701
702
703 @section Directive: include <source> [<destination>]
704
705 The 'include' directive can be used to include files or directories into
706 the distribution.  Sometimes it may be desired to specify included
707 files and directories in distribution instead of Makefile.am and
708 EXTRA_DIST, especially if there are many distributions that need to
709 include specific files and directories.  While it would be possible
710 to define them in Makefile.ad and use distdef conditionals to define
711 which will be included in which distribution, if there are many different
712 distributions it may pollute the Makefile.ad unnecessarily.
713
714 This directive is optional.  The <source> may be a single file, a  single
715 directory or a regular expression which will match several files and/or
716 directories.  The <destination> is optional.  If it is omitted then
717 the <source> will be copied into the same location in the distribution.
718 If the <destination> is provided the <source> will be copied into the
719 specified location.
720
721 Example:
722 @example
723 include apps/foobar/README README
724 include lib/libfoo
725 include lib/libfoobar lib/foobarlib
726 include doc/foo*
727 include scripts/foobar.sh foo.sh
728 @end example
729
730 Will include the file 'apps/foobar/README' into the top distribution
731 directory in the name 'README', the directory 'lib/libfoo' into same
732 location in distribution, the directory 'lib/libfoobar' into
733 'lib/foobarlib' changing the name of the directory into 'foobarlib',
734 the files and directories that match 'doc/foo*' into the same locations
735 in distribution, and finally the 'scripts/foobar.sh' into the top
736 distribution directory changing the name of the file into 'foo.sh'.
737
738 Note that, the 'include' directives will be processed by the Autodist
739 only when the distribution is packaged (@pxref{Creating distribution, , , , }).  When preparing the source
740 tree for configuration and compilation (@pxref{Preparing source tree, , , , })
741 the 'include' directives are ignored.  This is same behavior as with
742 Makefile.am's EXTRA_DIST.
743
744 If the included file or directory does not exist the Autodist will
745 give an error and stop the distribution creation.  If the destination
746 file exist, it will be replaced with the included file.  If the
747 destination directory already exists, the contents of the source
748 directory will be copied into the directory.  Note that, the directory
749 will not be copied into the directory; if the <destination> is specified,
750 also the name of the <source> file or directory must be specified,
751 otherwise the 'include' will change the name into the one specified.
752
753 Example:
754 @example
755 include lib/libfoo lib
756 @end example
757
758 In this example the 'lib/libfoo' will be included as 'lib'.  If the 'lib'
759 already exists, this effectively copies the contents of the 'lib/libfoo'
760 into 'lib'.  In order to include the directory with same name, the
761 name must be specified.
762
763 Example:
764 @example
765 include lib/libfoo lib/libfoo
766 include lib/foobar new_lib/foobar
767 @end example
768
769 This will include the 'lib/libfoo' into 'lib/libfoo' in distribution,
770 and 'lib/foobar' into 'new_lib/foobar' in distribution.
771
772
773 @section Directive: exclude <filename> [...]
774
775 The 'exclude' directive can be used to exclude files and directories from
776 the distribution.  This directive is optional.  This directive is
777 processed before processing the 'include' directive.  The <filename>
778 can be a single file, a single directory or a regular expression that
779 will match several files and/or directories.
780
781 Example:
782 @example
783 exclude README
784 exclude doc/client*
785 @end example
786
787 This will exclude the file 'README' and anything that match 'doc/client*'.
788
789
790 @section Directive: noprocess <filename> [...]
791
792 The 'noprocess' directive can be used to tell Autodist specificly not to
793 process a file.  The Autodist will not process the file during
794 preparation or during distribution packaging.  This directive is optional.
795 One or more file can be specified in the 'noprocess' directive.  Zero or
796 more 'noprocess' directives can be used in distribution.  The <filename>
797 can be a single file or a regular expression that will match several files.
798 Note that, in current Autodist version 'noprocess' cannot be used to
799 specify directories.
800
801 Example:
802 @example
803 noprocess autodist.texi
804 noprocess apps/foo/*
805 @end example
806
807 Autodist will not process 'autodist.texi' file, and any file that match
808 'apps/foo/*'.  Note that, any subdirectory under 'apps/foo/' will not
809 match, and will be processed.
810
811 Also note that, 'noprocess' directive cannot be used to disallow 
812 processing of any file with '.ad' suffix.
813
814
815 @section Directive: pre-hook <filename> [...]
816
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, , , , }).
823
824 The scripts will get three (3) command line arguments when Autodist
825 executes the script: distribution name, distribution version and package
826 name of distribution.  The script may use these arguments if it needs them.
827
828
829 @section Directive: post-hook <filename> [...]
830
831 The 'post-hook' directive can be used define additional scripts that
832 will be run after the source tree is prepared.  This directive is
833 optional.  One or more scripts may be defined in one 'post-hook' directive.
834 Zero or more 'post-hook' directives may be set for distribution.  The
835 'post-hook' hook will be run immediately after the Autodist has finished
836 preparing the source three for configuration and compilation (@pxref{Preparing source tree, , , , }).  The Autodist will exit after it has run the
837 'post-hook' scripts.
838
839 The scripts will get three (3) command line arguments when Autodist
840 executes the script: distribution name, distribution version and package
841 name of distribution.  The script may use these arguments if it needs them.
842
843
844 @section Directive: pre-process-dist-hook <filename> [...]
845
846 The 'pre-process-dist-hook' directive can be used define additional
847 scripts that will be run when Autodist has started distribution creation.
848 This directive is optional.  One or more scripts may be defined in one
849 'pre-process-dist-hook' directive.  Zero or more 'pre-process-dist-hook'
850 directives may be set for distribution.  The 'pre-process-dist-hook' hook
851 will be run immediately after the Autodist has created the distribution
852 directory but has not yet started any distribution processing.
853
854 The scripts will get four (4) command line arguments when Autodist
855 executes the script: distribution name, distribution version, package
856 name of distribution and destination distribution directory name.  The
857 script may use these arguments if it needs them.
858
859
860 @section Directive: post-process-dist-hook <filename> [...]
861
862 The 'post-process-dist-hook' directive can be used define additional
863 scripts that will be run when Autodist has finished distribution
864 processing.  This directive is optional.  One or more scripts may be
865 defined in one 'post-process-dist-hook' directive.  Zero or more
866 'post-process-dist-hook' directives may be set for distribution.  The
867 'post-process-dist-hook' hook will be run immediately after the Autodist
868 has finished processing the destination distribution directory but has not
869 yet created the distribution package.
870
871 The scripts will get four (4) command line arguments when Autodist
872 executes the script: distribution name, distribution version, package
873 name of distribution and destination distribution directory name.  The
874 script may use these arguments if it needs them.
875
876
877 @section Directive: pre-dist-hook <filename> [...]
878
879 The 'pre-dist-hook' directive can be used define additional scripts that
880 will be run when Autodist has started distribution creation.  This directive
881 is optional.  One or more scripts may be defined in one 'pre-dist-hook'
882 directive.  Zero or more 'pre-dist-hook' directives may be set for
883 distribution.  The 'pre-dist-hook' hook will be run immediately after
884 the Autodist has started distribution creation, but has not yet created
885 the distribution directory.  This hook is run before 'pre-process-dist-hook'.
886
887 The scripts will get four (4) command line arguments when Autodist
888 executes the script: distribution name, distribution version, package
889 name of distribution and destination distribution directory name.  The
890 script may use these arguments if it needs them.
891
892
893 @section Directive: post-dist-hook <filename> [...]
894
895 The 'post-dist-hook' directive can be used define additional scripts that
896 will be run when Autodist has finished distribution creation.  This
897 directive is optional.  One or more scripts may be defined in one
898 'post-dist-hook' directive.  Zero or more 'post-dist-hook' directives may
899 be set for distribution.  The 'post-dist-hook' hook will be run
900 immediately after the Autodist has finished creating the distribution
901 package.  This is the last hook Autodist runs.
902
903 The scripts will get four (4) command line arguments when Autodist
904 executes the script: distribution name, distribution version, package
905 name of distribution and destination distribution directory name.  The
906 script may use these arguments if it needs them.
907
908
909 @section Running hooks
910
911 The Autodist runs the hooks in the following order:
912
913 Preparing source tree for configuration and compilation:
914
915 @example
916 <...Autodist started...>
917 pre-hook
918 <...preparation...>
919 post-hook
920 <...Autodist exits...>
921 @end example
922
923 Creating distribution:
924
925 @example
926 <...Autodist started...>
927 pre-dist-hook
928 <...distribution directory created...>
929 pre-process-dist-hook
930 <...processing all files, processing excludes and includes...>
931 post-process-dist-hook
932 <...creating distribution package...>
933 post-dist-hook
934 <...Autodist exits...>
935 @end example
936
937 When creating distribution the 'pre-hook' and 'post-hook' are not run.
938
939
940 @section Example distfile
941
942 The following is a simple distfile example.  The example assumes that the
943 distdefs prefix is 'SILC'.
944
945 @example
946 # SILC Client distribution
947 name SILC Client
948 package silc-client
949 bug-report silc-client-bugs@@silcnet.org
950 inherit common
951 inherit platform-unix
952 inherit platform-win32
953 define SILC_DIST_CLIENT
954 define SILC_DIST_CLIENTLIB
955 define SILC_DIST_IRSSI
956 undef SILC_DIST_MPI
957 exclude doc/draft*
958 pre-hook scripts/client-pre-run
959 post-process-dist-hook scripts/client-post-process
960 post-dist-hook scripts/client-post-dist-bin
961 @end example
962
963 @menu
964 * configure.ad files::          configure script for creating configure.ac
965 @end menu
966
967
968 @node configure.ad files
969 @section configure.ad files
970
971 Autodist creates 'configure.ac' file from the 'configure.ad' file.  The
972 'configure.ad' file is a rather normal 'configure.ac' except that it accepts
973 also Autodist macros.  Autodist also supports configure script fragments,
974 also named as 'configure.ad'.  Any 'configure.ad' file in the source tree
975 can be incorporated into the the top 'configure.ad' file.  Sometimes it may
976 be useful to split a large configure script into smaller fragments.
977 Especially in multi distribution system where certain libraries or features
978 can be excluded from certain distributions it may be useful to handle
979 their configuration from a configure fragment.  If the library is
980 excluded then also its configuration can be excluded.
981
982 If the software project already has a 'configure.ac' or 'configure.in'
983 file, the 'configure.ad' can be created by simply renaming the current
984 file to 'configure.ad'.  In this case the current configure script
985 must be edited to support Autodist.  This is done by replacing the
986 'AC_INIT' to 'AD_INIT'.  After specifying the 'AD_INIT' as the first
987 macro in the 'configure.ad', the Autodist support has been fully
988 integrated into the software project.
989
990 If your software project is going to use configure fragments, then
991 also Autodist macro 'AD_INCLUDE_CONFIGURE' must be used.  Autodist will
992 automatically combine the fragments with the top 'configure.ac' script.
993 To exclude a 'configure.ad' fragment from a distribution use the distdef
994 conditionals inside the 'configure.ad' fragment file.  If the distdef is
995 not defined the fragment will be excluded automatically.
996
997 The following macros are available in current Autodist version.
998
999 @defmac AD_INIT
1000
1001 The 'AD_INIT' macro is used in place of Autoconf macro 'AC_INIT'.  The
1002 'AD_INIT' must be the first macro in the 'configure.ad', just like the
1003 'AC_INIT' macro in 'configure.ac'.  The AD_INIT macro is used to deliver
1004 the distribution names, distribution version, package name and bug-report
1005 email address to the 'configure.ac' file that Autodist will create.
1006 The 'AC_INIT' macro must not be used in 'configure.ad' file.
1007
1008 This macro is mandatory and Autodist will exit with error if it is not
1009 specified in 'configure.ad'.  This macro has no arguments.
1010 @end defmac
1011
1012
1013 @defmac AD_INCLUDE_CONFIGURE
1014
1015 This macro is used to tell Autodist that it should include any other
1016 'configure.ad' fragment that is found from the source tree into the
1017 top 'configure.ad' file.  Note that, the 'configure.ad' fragments will
1018 be incorporated at the location where this macro is used in the
1019 'configure.ad'.  Usually this macro is placed just before the Autoconf
1020 macro 'AC_OUTPUT'.  This macro has no arguments.
1021
1022 Note that, the 'configure.ad' fragments are not real full featured
1023 configure scripts.  They must not use 'AD_INIT', 'AD_INCLUDE_CONFIGURE',
1024 'AC_INIT' or any other initialization macros.
1025
1026 @end defmac
1027
1028 @menu
1029 * Makefile.ad files::           Makefile.ad for creating Makefile.am
1030 @end menu
1031
1032
1033 @node Makefile.ad files
1034 @section Makefile.ad files
1035
1036 Autodist creates 'Makefile.am' files from 'Makefile.ad' files.  A software
1037 project do not need to use 'Makefile.ad' files if there is no need to
1038 use distdef conditionals inside makefiles.  Usually a multi distribution
1039 software project, however will need to define certain things to different
1040 distributions.  In these cases 'Makefile.ad' file needs to be created.
1041
1042 Even though it would be possible to use distdef conditionals also inside
1043 'Makefile.am' files, Autodist does not process 'Makefile.am' files when
1044 preparing the source tree for configuration and compilation (@pxref{Preparing source tree, , , , }).  Thus, the prepared environment would not be
1045 identical to the created distribution package (when the 'Makefile.am'
1046 will be processed), and configuration and compilation would be inconsistent.
1047 Basic rule is, if you need distdefs (@pxref{Distdefines, , , , }) inside
1048 makefiles, put them inside 'Makefile.ad' file.
1049
1050
1051 @menu
1052 * Other .ad files::             Other files with .ad suffix
1053 @end menu
1054
1055
1056 @node Other .ad files
1057 @section Other .ad files
1058
1059 Any file in the source tree can have the '.ad' suffix appended.  Autodist
1060 will process any file that has the suffix when the source tree is
1061 prepared for configuration and compilation (@pxref{Preparing source tree, , , , }).  If the files have distdef conditionals the Autodist will process them.
1062 The files will have the '.ad' suffix removed.
1063
1064 Basic rule is, if you need to process some file when preparing the
1065 source tree for configuration and compilation, add '.ad' suffix to it.
1066 Distdefs (@pxref{Distdefines, , , , }) can be used in any file in source
1067 tree but without '.ad' suffix Autodist will not process those files during
1068 preparation.  They will be processed when creating the distribution package.
1069 If you need processed files during configuration or compilation then they
1070 need to have '.ad' suffix.
1071
1072 Note that, the distdef format used in these files must be the non-source
1073 format, even if the file is source file.  This is because the distdefs
1074 are processed during source tree preparation, and the source file will
1075 have all distdefs removed when it is compiled.
1076
1077 @menu
1078 * Distdefines::                 Using distdefs in files
1079 @end menu
1080
1081
1082 @node Distdefines
1083 @section Using distribution defines (distdefs)
1084
1085 Distribution defines, or distdefs from now on, are used to define inside
1086 a file what will be included in the distribution.  Distribution may define
1087 many different distdefs, for example, based on feature sets, platforms, or
1088 for other similar reasons.  If distdef is not defined for the distribution
1089 but is used in a file, anything inside the distdef in that file will be
1090 removed when the distribution is packaged (@pxref{Creating distribution, , , , }).  This guarantees that only the files, directories and file content
1091 (such as source code) that is supposed to be delivered with the distribution
1092 are delivered.  Delivering files or code accidentally in the distribution
1093 cannot happen.
1094
1095 All other files, except files ending with '.ad' suffix are processed for
1096 distdefs only when the distribution is packaged.  Files ending with '.ad'
1097 suffix are processed for distdefs when preparing the source tree for
1098 configuration and compilation (@pxref{Preparing source tree, , , , }).
1099
1100 By default the distdefs are named '_DIST_XXX', where 'XXX' is the name of
1101 distdef.  However, many projects will want to define their own prefix
1102 for distdefs in the 'autodist.conf' configuration file (@pxref{autodist.conf, , , , }).
1103 In the following examples a prefix 'SILC' is used, hence the prefix for
1104 the distdefs are 'SILC_DIST_'.
1105
1106 The basic format for the distdefs are as follows:
1107
1108 @example
1109 #ifdef SILC_DIST_DEFINE
1110 #endif SILC_DIST_DEFINE
1111
1112 #ifndef SILC_DIST_DEFINE
1113 #endif SILC_DIST_DEFINE
1114
1115 #ifdef SILC_DIST_DEFINE
1116 #else !SILC_DIST_DEFINE
1117 #endif SILC_DIST_DEFINE
1118
1119 #ifndef SILC_DIST_DEFINE
1120 #else SILC_DIST_DEFINE
1121 #endif SILC_DIST_DEFINE
1122 @end example
1123
1124 This format should be used only in non-source files, as for example C and
1125 C++ compilers will not like this format inside a file.  In source files
1126 a compiler friendly format, defined below, should be used.
1127
1128 @example
1129 #ifdef SILC_DIST_DEFINE
1130 #endif /* SILC_DIST_DEFINE */
1131
1132 #ifndef SILC_DIST_DEFINE
1133 #endif /* SILC_DIST_DEFINE */
1134
1135 #ifdef SILC_DIST_DEFINE
1136 #else /* !SILC_DIST_DEFINE */
1137 #endif /* SILC_DIST_DEFINE */
1138
1139 #ifndef SILC_DIST_DEFINE
1140 #else /* SILC_DIST_DEFINE */
1141 #endif /* SILC_DIST_DEFINE */
1142 @end example
1143
1144 Note that, only the format defined above is supported.  Other more complex
1145 use of the preprocessor directives such as using '&&' and '||' in the
1146 '#ifdef' or '#ifndef' are not supported, and neither is '#elif'.  Also
1147 note, that the name of the distdef in '#else' and '#endif' directives in
1148 non-source format and in source format inside C comments (/* */), and the
1149 use of '!' character in the '#else' branch of '#ifdef'" are mandatory.
1150 Also note, that the distdef conditionals must be placed at the start of
1151 the line, they must not be indented.
1152
1153 The following example shows the use of non-source format:
1154
1155 @example
1156 SUBDIRS =                        \
1157 #ifdef SILC_DIST_SERVER
1158        server                    \
1159        server-foobar             \
1160 #endif SILC_DIST_SERVER
1161 #ifndef SILC_DIST_CLIENT
1162        tests                     \
1163 #endif SILC_DIST_CLIENT
1164 #ifdef SILC_DIST_TOOLKIT
1165        toolkit                   \
1166        toolkit-docs              \
1167 #else !SILC_DIST_TOOLKIT
1168        doc                       \
1169        lib                       \
1170 #ifdef SILC_DIST_CLIENT
1171        client                    \
1172 #endif SILC_DIST_CLIENT
1173 #endif SILC_DIST_TOOLKIT
1174 @end example
1175
1176 Say, in this example, your distribution has the SILC_DIST_CLIENT and
1177 SILC_DIST_SERVER defined, but not the SILC_DIST_TOOLKIT, the end result
1178 would be:
1179
1180 @example
1181 SUBDIRS =                        \
1182        server                    \
1183        server-foobar             \
1184        doc                       \
1185        lib                       \
1186        client                    \
1187 @end example
1188
1189 The lines defined specificly for the SILC_DIST_TOOLKIT, which in our
1190 example was not defined, were removed.  Also lines that specificly
1191 expected certain distdefs not to be defined ('#ifndef') were removed.
1192 (Note the last remaining '\' in example above would be removed by the
1193 Autodist automatically to avoid errors with Automake.)
1194
1195 The following example shows the use of source code format:
1196
1197 @example
1198   initialize_lib();
1199 #ifdef SILC_DIST_MPI
1200   init_mpi();
1201   mpi = mpi_alloc();
1202 #else /* !SILC_DIST_MPI */
1203   init_gmp();
1204 #endif /* SILC_DIST_MPI */
1205
1206 #ifndef SILC_DIST_FOOBAR
1207   foobar_replacement();
1208   foobar_hack_init();
1209   foobar_init();
1210 #else /* SILC_DIST_FOOBAR */
1211   real_foobar();
1212 #endif /* SILC_DIST_FOOBAR */
1213 @end example
1214
1215 Say, you have both SILC_DIST_MPI and SILC_DIST_FOOBAR defined, the end result
1216 would be:
1217
1218 @example
1219   initialize_lib();
1220   init_mpi();
1221   mpi = mpi_alloc();
1222
1223   real_foobar();
1224 @end example
1225
1226 Even before processing the source files with Autodist, the preprocessor
1227 will respect the preprocessor directives if the code use '#include' to
1228 include the distdef header file created by the Autodist (see
1229 'autodist.conf' (@pxref{autodist.conf, , , , })).  When the distribution
1230 is packaged (@pxref{Creating distribution, , , , }) the Autodist will
1231 process the files, and will remove any line not defined to be included.
1232 The preprocessor directives will also be removed.
1233
1234 Because the software project includes the header file with '#include' the
1235 distdef header file needs to be present in the distribution, unless it is
1236 placed inside some other '#ifdef' conditional.  If the distribution is
1237 prepared but not compiled (it is packaged after preparation without
1238 compilation) then including the distdef header in the source is not
1239 necessary.  Including it then in the distribution is not necessary either.
1240
1241 The software project should not use the same name space that distdef
1242 conditionals use for other than distribution usage.  The Autodist will
1243 process any line that uses the formats above and has the specified prefix
1244 (eg. 'SILC_DIST_') in those lines.  Using same prefix for other purposes
1245 will produce unexpected results and invalid distributions.
1246
1247 The following suffixes will be considered as source files by the Autodist:
1248
1249 @example
1250     .c
1251     .C
1252     .cc
1253     .cp
1254     .cpp
1255     .CPP
1256     .cxx
1257     .CXX
1258     .c++
1259     .m
1260     .h
1261     .H
1262     .hh
1263 @end example
1264
1265 Also, any file that has '.in' suffix with any of the above source file 
1266 suffixes, the format inside the file must follow the source code format.  
1267 Using distdefs in any other file must follow the non-source format.
1268
1269 Example:
1270 @example
1271     .c.in
1272     .h.in
1273 @end example
1274
1275 In this example, in both of the files the source code format is used.
1276
1277
1278 @node Invoking Autodist
1279 @chapter Invoking Autodist
1280
1281 The Autodist has two basic functions:
1282
1283     1. Preparing source tree for configuration and compilation (@pxref{Preparing source tree, , , , })
1284
1285     2. Creating distribution packages (@pxref{Creating distribution, , , , })
1286
1287 The 'autodist' accepts the following options:
1288
1289 @table @samp
1290
1291 @item -h
1292 @itemx --help
1293 Prints the help for the Autodist and exits.
1294
1295 @item -V
1296 @itemx --version
1297 Prints version number and exits.
1298
1299 @item -v
1300 @itemx --verbose
1301 Verbosely report processing.
1302
1303 @item -d
1304 @itemx --distdir <dir>
1305 Search distributions from <dir> instead of default 'distdir'.
1306
1307 @item -s
1308 @itemx --distdefs [<dist>]
1309 Prints distribution defines of <dist> and exits.
1310
1311 @item -i
1312 @itemx --init
1313 Initializes Autodist environment.  Creates the default distribution
1314 directory 'distdir', 'autodist.conf' configuration file and the
1315 default distribution 'default', then exits.
1316
1317 @item -m
1318 @itemx --makedist
1319 Creates and packages distribution
1320
1321 @itemx --gzip
1322 Create package compressed with gzip (default)
1323
1324 @itemx --bzip2
1325 Create also package compressed with bzip2
1326
1327 @itemx --compress
1328 Create also package compressed with compress
1329
1330 @itemx --zip
1331 Create also package compressed with zip
1332
1333
1334 @end table
1335
1336 @menu
1337 * Preparing source tree::       Preparing source tree with Autodist
1338 * Creating distribution::       Creating distribution with Autodist
1339 @end menu
1340
1341
1342 @node Preparing source tree
1343 @section Preparing source tree for configuration and compilation
1344
1345 Before distribution can be created from the source tree, the source tree
1346 must be prepared for configuration and compilation.  If your project is
1347 not using Autodist, then you would do this by running perhaps 'aclocal',
1348 'autoconf', 'autoheader' and 'automake' tools manually, or you would run an
1349 'autogen.sh' script that prepares your raw source tree.  With Autodist
1350 this process is performed by Autodist, and running these tools manually
1351 or using 'autogen.sh' script is not necessary.
1352
1353 By default the 'autodist.conf' (@pxref{autodist.conf, , , , }) has defined
1354 the tools that will be run by the Autodist when preparing the source tree.
1355 These are 'aclocal', 'autoheader', 'autoconf', 'automake' and
1356 'libtoolize'.  If you do not wish that Autodist runs some or any of these
1357 tools automatically, do not set them in the 'autodist.conf'.  You would
1358 then need to run them manually. However, this is not recommended.  If you
1359 need to run additional preparation scripts you may set your scripts either
1360 in the 'pre-hook' and/or 'post-hook' where you can run what ever
1361 additional processing you may need to prepare your source tree.
1362
1363 By default the Autodist creates a 'default' distribution when you
1364 initialize your project by running 'autodist -i'.  The 'default'
1365 distribution should be used when you are developing in your source
1366 tree.  By default, the 'default' distribution cannot be packaged,
1367 however, if your project creates only one distribution you may find
1368 it more convenient to define your distribution inside the 'default'
1369 distribution and allow it to be packaged also.  If your source tree
1370 will create multiple distributions, the 'default' should be used only
1371 as development distribution.  You would use it when you, for example,
1372 checkout your source tree from CVS and prepare it for configuration
1373 and compilation.  To prepare your source tree with the 'default'
1374 distribution run Autodist without any arguments.
1375
1376 @example
1377   autodist
1378 @end example
1379
1380 The Autodist will prepare your source tree.  After that you may run
1381 './configure' and continue to compile with 'make'.
1382
1383 If you do not wish to use the 'default' distribution, or you wish
1384 to do the development in a tree specificly prepared for some specific
1385 distribution, or you are preparing to create a new distribution package,
1386 you will need to run the Autodist with the distribution you wish to
1387 prepare.
1388
1389 @example
1390   autodist example-distribution 1.0.3
1391 @end example
1392
1393 This prepares your source tree for 'example-distribution' of version
1394 '1.0.3'.  After that you may run './configure' and continue to compile
1395 with 'make'.  If the version is omitted the version will be '0.0'.
1396 The 'PACKAGE_VERSION' define delivered by Autoconf will contain this
1397 version.
1398
1399 Note that, running Autodist for preparation merely prepares your source
1400 tree for the distribution, it does not create an actual distribution
1401 package.  When preparing source tree for configuration and compilation
1402 the Autodist will process any file that ends with '.ad' suffix.  It will
1403 process all 'configure.ad' and 'Makefile.ad' files for that distribution.
1404 When you run './configure' your tree will be configured for that
1405 distribution, and when you compile with 'make' it will compile for that
1406 distribution.
1407
1408 However, the source files, or any other file (except files ending with
1409 '.ad' suffix) are not processed by the Autodist.  When compiling
1410 your sources the preprocessor, however, will respect your distdef
1411 conditionals inside your source files if you '#include' the distdef header
1412 file.  This way, even the compiled binaries will be compiled for that
1413 distribution, even though the source files has not yet been processed
1414 by the Autodist.  Rest of the files in the distribution will be processed
1415 when you create the actual distribution package.  It is guaranteed that
1416 the distribution you have prepared will behave in your source tree exactly
1417 the same way as if it was already packaged with Autodist (providing that
1418 you remember to include the distdef header file in your code).
1419
1420 When preparing the source tree Autodist will create a file 'autodist.dist'
1421 which will contain information on the prepared distribution.  When
1422 Creating the distribution that file will be read by the Autodist
1423 automatically.  That file should not be removed or the distribution
1424 cannot be packaged.
1425
1426 Autodist also created a log file, 'autodist.log', that will include
1427 messages created by Autodist during preparation.
1428
1429 @menu
1430 * Creating distribution::       Creating distribution with Autodist
1431 @end menu
1432
1433
1434 @node Creating distribution
1435 @section Creating distribution package(s)
1436
1437 Before creating a new distribution package, you will need to prepare
1438 the source tree for the distribution you want to create.  After preparing
1439 your source tree you will be ready to create a new distribution.  The
1440 Autodist package provides a simple helper script 'makedist' that may
1441 be used to create the distribution.  However, if you wish, you may
1442 run the Autodist yourself, as the 'makedist' will call Autodist anyway.
1443
1444 To create a new distribution for the distribution you have prepared for,
1445 run first './configure' and then 'makedist'.
1446
1447 @example
1448   makedist
1449 @end example
1450
1451 This will run the Autodist and create a new distribution package that
1452 is archived with 'tar' and compressed with 'gzip'.  If you wish to
1453 create packages also compressed with 'bzip2', 'compress' and/or 'zip'
1454 you may give one or all of the following options:
1455
1456 @example
1457   makedist --bzip2 --compress --zip
1458 @end example
1459
1460 This example would create, in addition of 'tar.gz' package, also a
1461 'tar.bz2', 'tar.Z' and '.zip' packages.  Current version of Autodist does
1462 not support archiving with 'shar'.
1463
1464 If you wish to run additional processing for your distributions when they 
1465 are being packaged you may set 'pre-process-dist-hook', 
1466 'post-process-dist-hook, 'pre-dist-hook' and/or 'post-dist-hook' in your 
1467 distribution file.  Also note that any hooks provided by Automake in 
1468 Makefiles will be run in normal manner.
1469
1470 When creating the distribution Autodist creates a log file, 
1471 'makedist.log', that will include messages created by Autodist.  It is 
1472 suggested that this file is checked after distribution is created.  For 
1473 example, when the 'license-header' directive is used to re-license the 
1474 distribution, the 'makedist.log' will include list of files that were not 
1475 re-licensed.  The log file can be used to verify that the distribution was 
1476 re-licensed correctly, and fix any possible mistakes.
1477
1478
1479 @node Examples
1480 @chapter Examples
1481
1482 @menu
1483 * Single distribution tree::    Single distribution example
1484 * Multiple distribution tree::  Multiple distributions example
1485 @end menu
1486
1487 @node Single distribution tree
1488 @section Single distribution tree example, start to finish
1489
1490 Lets suppose you have a simple source tree with one application,
1491 called 'foozbar' you wish to release.  While you would probably suffice
1492 using Autoconf and Automake features you may still use Autodist.
1493
1494 First, you create the default 'distdir' into your software package:
1495
1496 @example
1497   autodist -i
1498 @end example
1499
1500 Then, you create the 'configure.ad' file from your existing 'configure.ac'
1501 or 'configure.in' file.  If you don't have configure script written yet,
1502 please refer to the Autoconf manual.  In the 'configure.ad' you add as
1503 first macro in the file:
1504
1505 @example
1506   AD_INIT
1507 @end example
1508
1509 Then, you create distribution file for your application:
1510
1511 @example
1512 # Foozbar distribution
1513 name Foozbar
1514 package foozbar
1515 bug-report foozbar-bugs@@foo.z.bar
1516 define _DIST_FOOZBAR
1517 @end example
1518
1519 This distribution file go into 'distdir/foozbar'.
1520
1521 And there you go.  You have succesfully integrated Autodist into your
1522 source tree.  If you need to do development and you wish to use the
1523 'default' distribution for that, you should inherit the new 'foozbar'
1524 distribution in it.  Add the following line in 'distdir/default':
1525
1526 @example
1527   inherit foozbar
1528 @end example
1529
1530 After that, you can prepare the source tree for configuration and
1531 compilation by giving:
1532
1533 @example
1534   autodist
1535 @end example
1536
1537 After this command you can give './configure' and 'make'.
1538
1539 If you want to do development directly in a tree prepared for the
1540 'foozbar' distribution, or you are ready to start creating a new
1541 distribution package, you give:
1542
1543 @example
1544   autodist foozbar 1.0
1545 @end example
1546
1547 After this command you can give './configure' and 'make'.
1548
1549 To create the distribution package, you will give:
1550
1551 @example
1552   makedist
1553 @end example
1554
1555 The end result will be a 'foozbar-1.0.tar.gz' package.
1556
1557
1558 @node Multiple distribution tree
1559 @section Multiple distribution tree example, start to finish
1560
1561 Lets suppose you have a source tree from which you create multiple
1562 distributions, say three.  If you really have a such source tree you
1563 must have by now noticed the difficulty of maintaining such a source tree
1564 and problems with controlling the distributions.  Maybe you have sufficed
1565 with Autoconf and Automake, or perhaps you have created your own scripts
1566 that carry out the kludges.  No more, for Autodist is here.
1567
1568 First, you integrate Autodist into your tree by creating the distributions
1569 directory 'distdir':
1570
1571 @example
1572   autodist -i
1573 @end example
1574
1575 Then, you create the 'configure.ad' file from your existing 'configure.ac'
1576 or 'configure.in' file.  If you don't have configure script written yet,
1577 please refer to the Autoconf manual.  In the 'configure.ad' you add as
1578 first macro in the file:
1579
1580 @example
1581   AD_INIT
1582 @end example
1583
1584 You then continue with creating the distribution files for your three
1585 distributions.  Let's name them 'foozbar', 'libfoozbar' and 'nomad'.
1586 We will also create a common template that all distributions inherit.
1587
1588 @example
1589 # Foozbar distribution
1590 name Foozbar
1591 package foozbar
1592 bug-report foozbar-bugs@@foo.z.bar
1593 inherit common
1594 define _DIST_FOOZBAR
1595 @end example
1596
1597 @example
1598 # libfoozbar distribution
1599 name libfoozbar
1600 bug-report libfoozbar-bugs@@foo.z.bar
1601 inherit common
1602 define _DIST_LIBFOOZBAR
1603 @end example
1604
1605 @example
1606 # Nomad distribution
1607 name Nomad
1608 package nomad-the-server
1609 bug-report nomad-bugs@@foo.z.bar
1610 inherit common
1611 include doc/nomad
1612 define _DIST_NOMAD
1613 define _DIST_NOMAD_LIB
1614 undef _DIST_CRYPTO
1615 @end example
1616
1617 @example
1618 # Common template
1619 option template
1620 define _DIST_DOC
1621 define _DIST_LIB
1622 define _DIST_MATH
1623 define _DIST_CRYPTO
1624 define _DIST_UNIX
1625 define _DIST_MACOSX
1626 define _DIST_WIN32
1627 @end example
1628
1629 You put the distribution files in the 'distdir' directory.  In addition
1630 you will be doing development in the source tree using the 'default'
1631 distribution, you will add the new distributions to the 'distdir/default':
1632
1633 @example
1634 inherit foozbar
1635 inherit libfoozbar
1636 inherit nomad
1637 @end example
1638
1639 To prepare the source tree for configuration and compilation you would
1640 simply give:
1641
1642 @example
1643 autodist
1644 @end example
1645
1646 This will prepare your source tree for configuration and compilation.  Since
1647 the 'default' distribution inherits all distributions your development
1648 source tree will have all of them included.  If you do not want to do this
1649 then don't inherit them in the 'default', but run the autodist specificly
1650 for the distributions, for example:
1651
1652 @example
1653 autodist foozbar
1654 @end example
1655
1656 Since all the distributions inherit the 'common' distribution they get
1657 all the distdefs that the 'common' defines.  In this example various distdefs
1658 has been defined.  You would use them in your code and in your makefiles
1659 to control various things.  For example, let's say the 'common' distdefs
1660 control what directories distributions have.  An example 'Makefile.ad'
1661 file:
1662
1663 @example
1664 SUBDIRS =                       \
1665 #ifdef _DIST_LIB
1666        lib                      \
1667 #endif _DIST_LIB
1668 #ifdef _DIST_DOC
1669        doc                      \
1670 #endif _DIST_DOC
1671 @end example
1672
1673 Perhaps the 'Makefile.ad' in 'lib' subdirectory could define something
1674 like this:
1675
1676 @example
1677 SUBDIRS =                       \
1678         util                    \
1679 #ifdef _DIST_MATH
1680         mathlib                 \
1681 #endif _DIST_MATH
1682 #ifdef _DIST_CRYPTO
1683         cryptolib               \
1684 #endif _DIST_CRYPTO
1685 #ifdef _DIST_NOMAD_LIB
1686         nomadlib                \
1687 #endif _DIST_NOMAD_LIB
1688 #ifdef _DIST_LIBFOOZBAR
1689         foozbarlib               \
1690 #endif _DIST_LIBFOOZBAR
1691 @end example
1692
1693 Since the 'nomad' distribution undefined the '_DIST_CRYPTO' distdef it
1694 would not have the 'cryptolib' in its distribution.  Clearly Nomad
1695 don't need it.  In addition of using the distdefs just in the makefiles
1696 you may want to use them in the source code as well:
1697
1698 @example
1699      ...some code...
1700
1701 #ifdef _DIST_MATH
1702   /* Initialize math library */
1703   math_init();
1704 #endif /* _DIST_MATH */
1705
1706      ...some code...
1707 @end example
1708
1709 After an intensive development period you're ready to create new releases.
1710 Let's say you're going to release all distributions:
1711
1712 First you release Foozbar 0.5.1:
1713
1714 @example
1715 autodist foozbar 0.5.1
1716 makedist --bzip2
1717 @end example
1718
1719 The end result is two files: 'foozbar-0.5.1.tar.gz' and
1720 'foozbar-0.5.1.tar.bz2'.
1721
1722 Then you continue with libfoozbar and Nomad:
1723
1724 @example
1725 autodist libfoozbar 1.0.5
1726 makedist
1727
1728 autodist nomad 2.0
1729 makedist
1730 @end example
1731
1732 The end results are: 'libfoozbar-1.0.5.tar.gz' and 'nomad-2.0.tar.gz'.
1733
1734 @page
1735 @contents
1736 @bye