#! /usr/bin/perl # This file is part of GNU Dico # Copyright (C) 2014-2019 Sergey Poznyakoff # # GNU Dico 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; either version 3, or (at your option) # any later version. # # GNU Dico 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. # # You should have received a copy of the GNU General Public License # along with GNU Dico. If not, see . =head1 NAME bootstrap - Bootstrap the Dico project =head1 SYNOPSIS B [B<-ahmnv>] [B<--add>] [B<--dry-run>] [B<--help>] [B<--new>] [B<--modules>] [B<--skip-reconfig>] [B<--verbose>] [B<--quiet>] [B<--skip-po>] [I...] =head1 DESCRIPTION Bootstrap the Dico project. This is the first command that should be run after cloning the project from the repository in order to be able to built it. When run without arguments performs the following actions: =over 4 =item 1. Pulls in git submodules. =item 2. Creates directories and placeholders for automatically generated files =item 3. Creates autoconf/automake sources for building Dico modules. Recreates F and F from stub files F and F. The list of modules is obtained from the contents of the F directory -- each subdirectory is supposed to contain one module. Additional F code for each module is obtained from file F in each module directory. See the description of this file in section B. =item 4. Bootstraps the B submodule. The F is run with arguments deduced from files F and F. =item 5. Creates the file F This file is created from F using the information obtained from F and F. =item 6. Downloads new translations (F<*.po> files) into the F directory. This step can be skipped using the B<--skip-po> option. =item 7. Creates a pristine configuration header file The pristine configuration header file is a version of F stripped off any defines added by B. It is used by library source files to avoid introducing dependency on B. The name of the pristine header file is taken from the second argument of the B statement in the F file. =item 8. Reconfigures the project. =back The program must be run from the Dico source tree topmost directory. When given the B<-m> (B<--modules>) option, only the second step is performed. When the B<-a> (B<--add>, B<--new>) option is given, the program creates basic infrastructure for modules named in the command line. For each I from the command line it creates directory F> and populates it with files from the directory F. To this effect, it reads the list of file names from the section B of the file F. This file is in Emacs outline format. The B section lists file names relative to the F directory, one file per line. File names must start at column 1. A whitespace character (space or tab) starts a comment that spans to the physical end of line. Empty lines are ignored. Each file name from that list is copied to the newly created F> directory, creating eventual intermediate directories on the fly. E.g. the file F is copied to F/test/Makefile.am>. In the process some files undergo I, in which macro variables appearing in the source file are replaced with their actual values in the destination file. This process is discussed in detail in section B, below. Finally, the files F and F are recreated to take into account the newly created modules. By default, the program prints a succint report of what is being done. This can be changed using the B<-q> (B<--quiet>) and B<-v> (or B<--verbose>) options. The B<-q> (B<--quiet>) option instructs the program to suppress any output excepting error messages. The B<-v> (or B<--verbose>) option, on the contrary, instructs it to also print whatever output that was generated when running auxiliary commands. The B<-n> (B<--dry-run>) option instructs the tool to print what would have been done without actually doing it. =head1 OPTIONS =over 4 =item B<-a>, B<--add>, B<--new> Create basic infrastructure for modules named in the command line and add them to F and F =item B<-n>, B<--dry-run> Don't do anything, just print what would have been done. =item B<-m>, B<--modules> Run only the second step: creation of autoconf/automake sources for Dico modules. =item B<--skip-po> Don't synchronize localization files with the Translation Project. =item B<-s>, B<--skip-reconfigure> Don't run B. Takes effect only with B<--add> (B<--new>) or B<--modules>. =item B<-v>, B<--verbose> Increase output verbosity. Multiple options accumulate. =back The following options are passed to the B bootstrap script verbatim: =over 4 =item B<--gnulib-srcdir=>I Specifies the local directory where B sources reside. Use this if you already have gnulib sources on your machine, and do not want to waste your bandwidth downloading them again. =item B<--no-git> Do not use git to update B. Requires that B<--gnulib-srcdir> point to a correct gnulib snapshot. =item B<--skip-po> Do not download po files. =back The following options cause the program to display informative text and exit: =over 4 =item B<-h> Show a short usage summary. =item B<--help> Show man page. =item B<--usage> Show a concise command line syntax reminder. =back =head1 FILES The following files are used as templates to create output files. When creating output file, each line from the corresponding template is read, I is performed, and the resulting string is written to the output file. During macro expansion, each occurrence of B<< > >> is replaced with the contents of the macro variable I, if it is defined. Expansion of undefined variables leaves the text as is. The construct B<< #I> >> is expanded if it appears on a line alone, possibly preceded by any string of characters. It works similarly to B<< > >>, except that if I expands to multiple lines, the second and subsequent lines of expansion are prefixed with I on output. If I is empty, the content of the source line immediately preceding the construct is used instead. This makes it possible to use expansions after a comment character. E.g. if the variable B contains: This file is generated automatically. Please, do not edit. See the docs for more info. and the input file contains: dnl Then, the resulting expansion will be: dnl This file is generated automatically. dnl Please, do not edit. dnl See the docs for more info. The macro variables are specific for each file, and are described below. For each file, a special comment sequence is defined. Lines beginning with that sequence are omitted from the output. =over 4 =item F Produces the F file. Comment marker is B<##>. The following variables are defined: =over 8 =item B B code for each module, obtained from the F files. =item B Generates an initial header text, warning the reader that the file is generated automatically and informing him about the ways to recreate that file. =item B A list of printable description for modules that can be disabled. Each module is represented with a line MODNAME ................ STATUS where MODNAME is the module name and STATUS is the module status variable (which produces B or B at configure time, depending on whether the module is enabled or not). This is intended for use in B. =item B A list of assignments for module status variables, intended for use in B. =back The following code illustrates the use of the latter two variables: AC_CONFIG_COMMANDS([status],[ echo ], []) =item F This file is optional. If present, it contains the B code for that module, which is appended to the contents of the B variable used for creating F. No macro substitutions are performed for that file. Comment marker is B<##>. The following comments starting with B<## module> are I ones, and are treated specially: =over 8 =item B<## module name: I> Use I as module name when creating variable names for that module. This is useful when the module name contains symbols that cannot be used in variable names (as in, e.g. B). =item B<## module description: I> Use I as module description in B (see F). =item B<## module category:> Reserved for future use. =back As well as other B<##> comments, these comments do not appear in the output. =item F Produces the file F. Comment marker is B<##>. Macro variables: =over 8 =item B Same as in F. =item B Produces B code for the B variable. =item B