X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=apps%2Fautodist%2Fdoc%2Fautodist.texi;fp=apps%2Fautodist%2Fdoc%2Fautodist.texi;h=0000000000000000000000000000000000000000;hb=72c2de619079457f7a68100eb13385275a424a23;hp=aadb62fca86dad87e06d086aa9c9c8895298ef26;hpb=e7b6c157b80152bf9fb9266e6bdd93f9fb0db776;p=runtime.git diff --git a/apps/autodist/doc/autodist.texi b/apps/autodist/doc/autodist.texi deleted file mode 100644 index aadb62fc..00000000 --- a/apps/autodist/doc/autodist.texi +++ /dev/null @@ -1,1812 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename autodist.info -@settitle autodist -@setchapternewpage off -@c %**end of header - -@include version.texi - -@copying - -This manual is for SILC Autodist (version @value{VERSION}, -@value{UPDATED}), a program which is used to manage and create source -distributions. - -Copyright @copyright{} 2004 - 2005 Pekka Riikonen, SILC Project - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the @acronym{GNU} Free Documentation License, -Version 1.2 or any later version published by the Free Software -Foundation; with no Invariant Sections, with the Front-Cover texts -being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in -(a) below. A copy of the license is included in the section entitled -``@acronym{GNU} Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have freedom to copy and -modify this @acronym{GNU} Manual, like @acronym{GNU} software. Copies -published by the Free Software Foundation raise funds for -@acronym{GNU} development.'' -@end quotation -@end copying - -@dircategory Software development -@direntry -* autodist: (autodist). Managing and creating source distributions. -@end direntry - -@dircategory Individual utilities -@direntry -* makedist: (autodist)Invoking makedist. Creating distribution -@end direntry - -@titlepage -@title SILC Autodist -@subtitle For version @value{VERSION}, @value{UPDATED} -@author Pekka Riikonen -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@ifnottex -@node Top -@comment node-name, next, previous, up -@top SILC Autodist - -@insertcopying - -@menu -* Introduction:: Purpose of Autodist -* Integrating Autodist:: Integrating Autodist into your project -* Invoking Autodist:: Running Autodist -* Examples:: Examples using Autodist - -@detailmenu - --- The Detailed Node Listing --- - -Introduction - -* Motivation:: Reasons for using Autodist - -Integrating Autodist - -* Creating distdir:: Creating distributions directory -* autodist.conf:: Configuring Autodist -* Creating new distribution:: Adding new distribution -* Distribution file format:: Detailed document for distfile format -* configure.ad files:: configure script for creating configure.ac -* Makefile.ad files:: Makefile.ad for creating Makefile.am -* Other .ad files:: Other files with .ad suffix -* Distdefines:: Using distdefs in files -* Dependencies:: Autodist dependency support - -Invoking Autodist - -* Preparing source tree:: Preparing source tree with Autodist -* Creating distribution:: Creating distribution with Autodist - -Examples - -* Single distribution tree:: Single distribution example -* Multiple distribution tree:: Multiple distributions example - -@end detailmenu -@end menu - -@end ifnottex - - -@node Introduction -@chapter Introduction - -The Autodist is a source distribution management system that allows -powerful mechanisms to define what is included in and excluded from a -distribution, and what license the distribution is released under. It is -also used to create the actual distribution source packages. Autodist -allows distribution management in file, directory and file content level. -Different distributions may include different portions of files, for -example, excluding certain features from certain distributions. It is -always guaranteed that anything not defined for the distribution, is -removed automatically (files, file content, directories), thus ensuring -that nothing is accidentally included in the distribution. - -The Autodist creates 'Makefile.am' files from 'Makefile.ad' files and -'configure.ac' file from one or more 'configure.ad' files. Any other file -ending with '.ad' suffix will also be processed. The processed file will -have the '.ad' suffix removed (@pxref{Preparing source tree, , , , }). -Autodist also creates and packages the distribution using common GNU -distribution creation process, specificly `make dist'. Autodist, however, -controls this process and during packaging phase the Autodist processes -all files in the distribution (other than '*.ad' files, which has already -been processed earlier by Autodist). The resulted package is a processed -source distribution package, processed according to the rules specified -in the distribution file(s) (@pxref{Creating distribution, , , , }). - -Any file in the source tree may use distdefs (distribution defines (@pxref{Distdefines, , , , })) which are defined in the distributions. When distribution -is packaged only the files, directories and file content that is either -outside of any distdef, or inside the defined distdefs will be included -in the distribution. Any other file, directory or content in the file -will be removed. It is guaranteed, if a file, a directory or a piece of -file content is not inside a defined distdef it will not be delivered to -the distribution. - -Any file, 'Makefile.am', 'configure.ac', or source file processed with -Autodist is always compliant with the tools needed to process them. All -files can also be processed with the corresponding tools even before -processing them with Autodist. This makes it possible, for example, to -compile sources before they have been processed, and undefined lines -are removed. The distdefs are respected in source files by the -preprocessor. - -Autodist is not a binary packaging system. It is specificly used to -create source distributions. A binary packaging system, however can be -hooked to the distribution creation process, if needed. - -@menu -* Motivation:: Reasons for using Autodist -@end menu - - -@node Motivation -@section Reasons for using Autodist - -Autodist is closely related to the Autoconf and Automake tools, and -complements the features Autoconf and Automake provides. It is especially -targeted into circumstances where multiple distributions are created from -one source tree. The Autoconf and Automake environment is mainly designed -for one distribution (one application) per one source tree situations. -Autodist provides mechanisms to create all kinds of distributions that can -be created from one source tree. To be able to use Autodist, the Autoconf -and Automake must be installed into the system (@pxref{Integrating Autodist, , , , }). -Autoconf version must be at least 2.52g. - -Small software projects usually do very well with Autoconf and Automake -and their distribution management features. Often these projects do not -need Autodist, though they can benefit from it. However, if your software -project is large, you need to create multiple distributions from one source -tree, you have complex licensing terms for different distributions, you -have different target users or customers that may require different -feature set or licenses in different distributions, you have need to -continue concurrent development in the main source tree and still be able -to create stable distributions, and/or you have need to control file -content in different distributions (to avoid distributing code or features -that aren't supposed to be distributed, or to avoid leaking information -to your competitors on what new features you are working on), then Autodist -is a tool you may find usefull. - -The motivation behind Autodist stems from need to be able to create -multiple distributions from one large source tree in a precise and -controllable manner, and guarantee that anything that is not part of the -distribution is removed from the distribution. The Autoconf and Automake -provides mere basic control what is included in and excluded from -distributions and how the distributions are created. They also do not -provide mechanism to define different licensing conditions for different -distributions, or changing the license automatically for different user -or customer purposes. Many large software projects, companies and -corporations have commonly been using Autoconf and Automake tools, but -have had the need to create their own ad-hoc mechanisms to control -distribution creation. The Autodist attempts to provide a tool that any -size software project can effectively use to manage their distributions. - -Without a tool like Autodist, large software projects usually has to be -split into separate source trees, which may not always be possible because -they may share large portions of common code (which may further make -concurrent development of the applications hard), or multiple Autoconf and -Automake environments (multiple configure scripts) needs to be created -in one source tree. In this case the source tree usually gets very -complicated and controlling what is compiled and what is included in -distributions becomes harder, especially when different parts code is shared -between applications and libraries. - - -@node Integrating Autodist -@chapter Integrating Autodist - -Integrating Autodist into existing software project can be a very simple -task or a fairly complicated task. It depends on the size and complexity -of the software project. Generally speaking, integrating Autodist into -software project is fairly straightforward process: - -1. The distributions directory and 'default' distribution are created - -2. The 'configure.ad' is created - -3. If needed, 'Makefile.ad' file(s) are created - -After this the Autodist can already be used to prepare the source tree -for configuration and compilation (@pxref{Preparing source tree, , , , }). -Adding a new distribution would then allow the actual distribution -packaging also. - -If the software project has had own ad-hoc distribution system already in -place, it may take some work to move from that system into the Autodist. -If there are multiple applications and distributions created from the -source tree, the distributions and distribution defines for them need to -be created. While this may be unthankful job, it only needs to be done -once. - -Integrating Autodist into a new software project is a very simple task as -renaming 'configure.ac' and possibly 'Makefile.am' files are not required, -as they may not exist yet. - - -@menu -* Creating distdir:: Creating distributions directory -* autodist.conf:: Configuring Autodist -* Creating new distribution:: Adding new distribution -* Distribution file format:: Detailed document for distfile format -* configure.ad files:: configure script for creating configure.ac -* Makefile.ad files:: Makefile.ad for creating Makefile.am -* Other .ad files:: Other files with .ad suffix -* Distdefines:: Using distdefs in files -* Dependencies:: Autodist dependency support -@end menu - - -@node Creating distdir -@section Creating distributions directory - -The distributions directory is 'distdir', which is expected to be -located in the root of the source tree. This directory will hold all -the distribution files, and the Autodist configuration file 'autodist.conf' (@pxref{autodist.conf, , , , }). -If this directory does not exist it can be created with the Autodist. - -@example - autodist -i -@end example - -This will create the 'distdir' and copy the default 'autodist.conf' -configuration file and the 'default' distribution into the directory. -The 'default' distribution will be used by default by the Autodist -unless other distribution is specified. - -After this the Autodist has effectively been integrated into the -software project. However, usually after this, one would create new -distributions, the 'configure.ad' and possibly 'Makefile.ad' file(s). -Without 'configure.ad' file a distribution package cannot be created. -However, even without 'configure.ad' file the source tree can be -prepared for configuration and compilation (@pxref{Preparing source tree, , , , }). - -@menu -* autodist.conf:: Configuring Autodist -@end menu - - -@node autodist.conf -@section Configuring Autodist - -After the Autodist has been integrated into the software by creating -the 'distdir', the 'autodist.conf' configuration file was added to the -'distdir' also. Usually software projects will want to modify some of -the 'autodist.conf' options, mainly specifying the distdef prefix. - -The 'autodist.conf' is a text file. The following options are available -in 'autodist.conf': - - -@example -DISTPREFIX="" -@end example - -By default the distdef prefix is '_DIST_'. To add own software package -specific prefix the 'DISTPREFIX' can be defined. - -Example: -@example -DISTPREFIX="SILC" -@end example - -Will set the distdef prefix as 'SILC_DIST_'. - - -@example -DISTDEFS="distdefs.h" -@end example - -The 'DISTDEFS' option specifies the file name of the distdef header file -which Autodist will create. The software project should '#include' the -header file in order for the preprocessor to respect the distdef -conditionals (@pxref{Distdefines, , , , }). By default the file name -is 'distdefs.h' and is created at the root of source tree. Other location -may be specified if needed. - -Example: -@example -DISTDEFS="include/distdefs.h" -@end example - - -@example -ACLOCAL="aclocal" -@end example - -The 'ACLOCAL' specifies the location of the 'aclocal' tool. If Autodist -should not run 'aclocal' this option may be removed or set to empty value. -User need to then run it manually. - - -@example -AUTOHEADER="autoheader" -@end example - -The 'AUTOHEADER' specifies the location of the 'autoheader' tool. If -Autodist should not run 'autoheader' this option may be removed or set -to empty value. User need to then run it manually. - -@example -AUTOCONF="autoconf" -@end example - -The 'AUTOCONF' specifies the location of the 'autoconf' tool. If -Autodist should not run 'autoconf' this option may be removed or set -to empty value. User need to then run it manually. - - -@example -AUTOMAKE="automake -a -c" -@end example - -The 'AUTOMAKE' specifies the location of the 'automake' tool. If -Autodist should not run 'automake' this option may be removed or set -to empty value. User need to then run it manually. By default, the -'-a' and '-c' options are given to 'automake' to add any missing required -files. - - -@example -LIBTOOLIZE="libtoolize --automake -c" -@end example - -The 'LIBTOOLIZE' specifies the location of the 'libtoolize' tool. -This option should be removed or ste to empty value if 'libtool' is not -used in the source tree. - - -@example -MAKE=make -@end example - -The 'MAKE' specifies the location of the 'make' program. This option must -be set to valid value in order to create distributions. - - -@menu -* Creating new distribution:: Adding new distribution -@end menu - - -@node Creating new distribution -@section Creating new distribution - -After the Autodist has been integrated into the software project by -creating the 'distdir' and 'default' distribution, the source tree -can be prepared for configuration and compilation (@pxref{Preparing source tree, , , , }). However, the 'default' distribution should be used only as -a development distribution. Usually it is used to prepare the raw source -tree (such as a tree just checkout -from CVS) for configuration and compilation. By default, the 'default' -distribution cannot be packaged. However, if the software project is -small (one distribution), it may be convenient to edit the 'default' -distribution to be as the distribution that is packaged from the source -tree. In software project where multiple distributions are created using -the 'default' only as a development distribution is recommended. The -real distributions should be defined as separate distributions. - -Creating a new distribution is a simple process. Each distribution -is placed in the 'distdir' and the file name of the distribution file is -used to reference to it. By default, the distribution name is the -file name of the distribution file. The actual distribution file is -a simple text file with various directives that define the distribution. - -If the 'default' distribution is used as a development distribution it -might be desired to inherit some or all of the created distributions in -it, so that development becomes possible with the 'default' distribution. -Adding 'inherit' directive into the 'distdir/default' will inherit the -specified distribution. - - -@menu -* Distribution file format:: Detailed document for distfile format -@end menu - - -@node Distribution file format -@section Distribution file format in detail - -The distribution file, or distfile from now on, defines your distribution, -distribution defines, options, included and excluded files and -directories, license, and additional processing. Each distribution is -defined in a separate file and the distributions are referenced by -their file name. - -The distfile is a text file that contains various directives that define -the actual distribution. Lines starting with '#' are considered comments -and are ignored. - - -@section Directive: name - -The 'name' directive defines the name of the distribution. It is optional -directive, and if omitted the distribution name will be the name of the -distfile. The 'PACKAGE_NAME' define delivered by Autoconf will contain -this name string. - -Example: -@example -name FOO Application -@end example - -Will set your distribution name as 'Foo Application'. - - -@section Directive: package - -The 'package' directive defines the name of the distribution package. It is -optional directive, and if omitted the distribution package name will -be the name of the distribution, if defined, or if omitted, then the name -of the distfile. If this directive is omitted then normal GNU convention -is used to decide the package name, derived from the distribution name. -The 'PACKAGE_TARNAME' define delivered by Autoconf will contain this -package name string. - -Example: -@example -package foo-client -@end example - -Will create distribution packages named, for example, as -'foo-client-1.0.tar.gz'. - - -@section Directive: bug-report - -The 'bug-report' directive can be used to define the email address where -the bug-reports for the distribution should be sent. The directive is -optional. The 'PACKAGE_BUGREPORT' define delivered by Autoconf will -contain this bug report string. - - -@section Directive: license - -The 'license' directive can be used to define the license file for the -distribution. This directive is optional. The license file will be -copied into the distribution in the name 'COPYING'. If the 'COPYING' -file already exist it will be replaced. - -Example: -@example -license license/GPL -@end example - -Will include the file 'license/GPL' into the distribution in the file -name 'COPYING'. - - -@section Directive: license-header - -The 'license-header' can be used to re-license your files into a new -license. This directive is optional. There may be zero or more -'license-header' directives in distribution. The 'license-header' -directive will compare the license header that usually appear at the -start of a file to the . If it matches it will -be replaced with the . The license header in the file -will be replaced and the file will have effectively been re-licensed. - -Example: -@example -license-header license/BSD-header license/GPL-header -@end example - -Will replace all appearances of the license header in 'license/BSD-header' -file to the license header in 'license/GPL-header' in any file in the -distribution. Note that, the header change will be performed when -the distribution is packaged (@pxref{Creating distribution, , , , }). -The 'makedist.log' file created by Autodist during distribution packaging -will list all files that were not re-licensed. The log file can be used -to check that the distribution is re-licensed correctly, and fix any -possible mistakes. - -With 'license-header' directive you may initially set your files in the -source tree into what ever license you prefer. However, if you need to -re-license parts of the source tree in certain distributions the -'license-header' will achieve this automatically. For example, suppose -one wants to create two different versions of a library distribution, with -different feature sets, in two different licenses. - -There are several limitations in the current implementation of Autodist -with the 'license-header' directive: - -First limitation is that the header files must have equal amount of lines. -If the new header file has fewer lines that the current header file, all -of the lines from the current header will not be replaced. If the new header -has fewer lines, empty lines must be added to it. If the new header file -has more lines than the current header file, the extra lines will not appear -in the replaced header. Basic rule is to always make sure the header -files have equal amount of lines in them. - -Second limitation is in indentation of the header files. It is suggested, -though not mandatory, that the header files have the same indentation as -is commonly used in the source tree; if the license header text in a file -starts at the second character instead of at the start of the line, then -the header file should start the license text at the second character also. -If same indentation is not used the appearance of the replaced header -may not be perfect. While this is a cosmetic issue, one still to remember. - -Third limitation is that the distribution cannot be partially re-licensed. -If the 'license-header' directive is used then all files that have the -specified header will be replaced with the new header. There are -currently two ways to not re-license a file; use different license header -in the file than one specified in 'license-header', or specify the file or -directory in 'noprocess' directive. Using 'noprocess' is not possible if -the file needs to be otherwise processed for the distribution. Future -versions of Autodist may provide a mechanism to re-license only part of -the distribution. - -Example current header: -@example ---- Start example - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; version 2 of the License. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. ---- end example -@end example - -Example new header: -@example ---- Start example - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the conditions listed in the - COPYING file are met. - - - ---- end example -@end example - -In this example, if the text in the current header file is found in any -file in the distribution it will be replaced with the new header file. -Notice that, both header files has same amount of lines (8 lines). - -Note that, the current header must match exactly the header used in -files. Otherwise the replacement will not be complete. - - -@section Directive: prereq - -The 'prereq' may be used to enforce the Autodist version. If the Autodist -version used to process the distribution is older than the version -specified with 'prereq' the Autodist will fail. - -Example: -@example -prereq 1.3.2 -@end example - -Will require Autodist 1.3.2 or newer for this distribution. - - -@section Directive: inherit - -The Autodist provides inheritance of distributions. The 'inherit' -directive is used to define the distribution which will be inherited -into the distribution. The specifies the name of the -inherited distribution. If the distribution cannot be inherited Autodist -will give an error. - -The 'inherit' will inherit the following information from the -distribution: distdefs, undefines, includes, excludes and noprocesses. -Other information will not be inherited. If the inherited distribution -inherits other distributions, they will also be inherited automatically. -User should be careful when inheriting distributions as it may be possible -to create an infinite recursion. The Autodist would allow for this and -not detect this error. Zero or more 'inherit' directives may be set for -distribution. - -Example: -@example -inherit common -inherit client -inherit toolkit -@end example - -Will inherit distributions 'common', 'client' and 'toolkit' into this -distribution. All distdefs, undefines, includes, excludes and noprocesses -from these distributions are now also part this distribution. - -The distribution that is being prepared or packaged take precedence when -defining distdefs that were specificly undefined in the inherited -distribution. This means that if the inherited distribution specificly -undefines a distdefs but the inheriting distribution (one being prepared -or packaged) specificly defines it, the distdef will be defined. -Similarly, if the inherited distribution defines a distdef but the -inheriting distribution undefines it, the distdef will be undefined. -Note that, this precedence works only in the top distribution (the one -being prepared or packaged). If the inherited distribution inherits other -distributions, all distdefs (defined and specificly undefined) will be -inherited as is. This means that if one inherited distribution defines a -distdef that other inherited distribution distdef undefines, it will be -undefined. However, the top distribution can then override them if -needed. - - -@section Directive: define - -The 'define' directive is used to define the distdef symbols for the -distribution. This directive is optional, however, all distributions -should define at least one distdef so that the distribution may be -controlled with the distdef conditionals in files in the source tree (@pxref{Distdefines, , , , }). By default, the distdef prefix is '_DIST_'. Many -software projects will want to set their own prefix for the distdefs -for consistency. The prefix may be defined in the 'autodist.conf' file -(@pxref{autodist.conf, , , , }). - -Example: -@example -define _DIST_FOO -define _DIST_FEATURE_X -define _DIST_LIBRARY_Y -@end example - -Will define the following distdefs for the distribution: '_DIST_FOO', -'_DIST_FEATURE_X' and '_DIST_LIBRARY_Y'. These distdefs may then be -used in the source tree and source code to control what is included in -or excluded from this distribution. - - -@section Directive: undef - -The 'undef' directive may be used to explicitly undefine a distdef. -When inheriting distributions it may be desired to be able undefine -certain distdefs. This directive is optional. - -Example: -@example -undef _DIST_FEATURE_Y -@end example - -Will undefine '_DIST_FEATURE_Y' distdef. This distdef will not be part -of this distribution anymore, even if it is defined in some inherited -distribution. - - -@section Directive: option