diff options
Diffstat (limited to 'modinc')
-rwxr-xr-x | modinc | 641 |
1 files changed, 0 insertions, 641 deletions
@@ -1,641 +0,0 @@ | |||
1 | #! /usr/bin/perl | ||
2 | # This file is part of GNU Dico | ||
3 | # Copyright (C) 2014, 2016 Sergey Poznyakoff | ||
4 | # | ||
5 | # GNU Dico is free software; you can redistribute it and/or modify | ||
6 | # it under the terms of the GNU General Public License as published by | ||
7 | # the Free Software Foundation; either version 3, or (at your option) | ||
8 | # any later version. | ||
9 | # | ||
10 | # GNU Dico is distributed in the hope that it will be useful, | ||
11 | # but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
12 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
13 | # GNU General Public License for more details. | ||
14 | # | ||
15 | # You should have received a copy of the GNU General Public License | ||
16 | # along with GNU Dico. If not, see <http://www.gnu.org/licenses/>. | ||
17 | |||
18 | =head1 NAME | ||
19 | |||
20 | modinc - Recreate Dico module autoconf structure | ||
21 | |||
22 | =head1 SYNOPSIS | ||
23 | |||
24 | B<modinc> | ||
25 | [B<-ahnv>] | ||
26 | [B<--add>] | ||
27 | [B<--help>] | ||
28 | [B<--new>] | ||
29 | [B<--dry-run>] | ||
30 | [B<--verbose>] | ||
31 | [I<NAME>...] | ||
32 | |||
33 | =head1 DESCRIPTION | ||
34 | |||
35 | Recreates F<configure.ac> and F<modules/Makefile.am> from stub files | ||
36 | F<stub.ac> and F<modules/stub.am>. The list of modules is obtained | ||
37 | from the contents of the F<modules> directory -- each subdirectory | ||
38 | is supposed to contain one module. | ||
39 | |||
40 | Additional F<configure.ac> code for each module is obtained from | ||
41 | file F<module.ac> in each module directory. See the description of | ||
42 | this file in section B<FILES>. | ||
43 | |||
44 | When run with B<-a> (B<--add>, B<--new>) option, the program creates | ||
45 | basic infrastructure for modules named in the command line. For each | ||
46 | I<NAME> it creates directory F<modules/I<NAME>>. Withih that directory, | ||
47 | it creates two files: F<Makefile.am> from F<modules/template.am>, and | ||
48 | F<I<NAME>.c>, which contains a stub code for the module. | ||
49 | |||
50 | The program must be run from the Dico source tree topmost directory. | ||
51 | |||
52 | =head1 OPTIONS | ||
53 | |||
54 | =over 4 | ||
55 | |||
56 | =item B<-a>, B<--add>, B<--new> | ||
57 | |||
58 | Create basic infrastructure for modules named in the command line and | ||
59 | add them to F<configure.ac> and F<modules/Makefile.am> | ||
60 | |||
61 | =item B<-n>, B<--dry-run> | ||
62 | |||
63 | Don't do anything, just print what would have been done. | ||
64 | |||
65 | =item B<-v>, B<--verbose> | ||
66 | |||
67 | Increase output verbosity. Multiple options accumulate. | ||
68 | |||
69 | =back | ||
70 | |||
71 | The following options cause the program to display informative text and | ||
72 | exit: | ||
73 | |||
74 | =over 4 | ||
75 | |||
76 | =item B<-h> | ||
77 | |||
78 | Show a short usage summary. | ||
79 | |||
80 | =item B<--help> | ||
81 | |||
82 | Show man page. | ||
83 | |||
84 | =item B<--usage> | ||
85 | |||
86 | Show a concise command line syntax reminder. | ||
87 | |||
88 | =back | ||
89 | |||
90 | =head1 FILES | ||
91 | |||
92 | The following files are used as templates to create output files. When | ||
93 | creating output file, each line from the corresponding template is read, | ||
94 | I<macro expansion> is performed, and the resulting string is written to the | ||
95 | output file. | ||
96 | |||
97 | During macro expansion, each occurrence of B<< <I<NAME>> >> is replaced with | ||
98 | the contents of the macro variable I<NAME>, if it is defined. Expansion | ||
99 | of undefined variables leaves the text as is. | ||
100 | |||
101 | The construct B<< <I<NAME>#I<TEXT>> >> is expanded if it appears on a line | ||
102 | alone, possibly preceded by any string of characters. It works similarly | ||
103 | to B<< <I<NAME>> >>, except that if I<NAME> expands to multiple lines, the | ||
104 | second and subsequent lines of expansion are prefixed with I<TEXT> on output. | ||
105 | If I<TEXT> is empty, the content of the source line immediately preceding the | ||
106 | construct is used instead. This makes it possible to use expansions after a | ||
107 | comment character. E.g. if the variable B<HEADING> contains: | ||
108 | |||
109 | This file is generated automatically. | ||
110 | Please, do not edit. | ||
111 | See the docs for more info. | ||
112 | |||
113 | and the input file contains: | ||
114 | |||
115 | dnl <HEADING#> | ||
116 | |||
117 | Then, the resulting expansion will be: | ||
118 | |||
119 | dnl This file is generated automatically. | ||
120 | dnl Please, do not edit. | ||
121 | dnl See the docs for more info. | ||
122 | |||
123 | The macro variables are specific for each file, and are described below. | ||
124 | |||
125 | For each file, a special comment sequence is defined. Lines beginning | ||
126 | with that sequence are omitted from the output. | ||
127 | |||
128 | =over 4 | ||
129 | |||
130 | =item F<stub.ac> | ||
131 | |||
132 | Produces the F<configure.ac> file. Comment marker is B<##>. | ||
133 | The following variables are defined: | ||
134 | |||
135 | =over 8 | ||
136 | |||
137 | =item B<MODULES> | ||
138 | |||
139 | B<Autoconf> code for each module, obtained from the F<module.ac> | ||
140 | files. | ||
141 | |||
142 | =item B<HEADING> | ||
143 | |||
144 | Generates an initial header text, warning the reader that the file is | ||
145 | generated automatically and informing him about the ways to recreate | ||
146 | that file. | ||
147 | |||
148 | =item B<STATUS_OUTPUT> | ||
149 | |||
150 | A list of printable description for modules that can be disabled. Each | ||
151 | module is represented with a line | ||
152 | |||
153 | MODNAME ................ STATUS | ||
154 | |||
155 | where MODNAME is the module name and STATUS is the module status variable | ||
156 | (which produces B<yes> or B<no> at configure time, depending on whether | ||
157 | the module is enabled or not). | ||
158 | |||
159 | This is intended for use in B<AC_CONFIG_COMMANDS>. | ||
160 | |||
161 | =item B<STATUS_DEFN> | ||
162 | |||
163 | A list of assignments for module status variables, intended | ||
164 | for use in B<AC_CONFIG_COMMANDS>. | ||
165 | |||
166 | =back | ||
167 | |||
168 | The following code illustrates the use of the latter two variables: | ||
169 | |||
170 | AC_CONFIG_COMMANDS([status],[ | ||
171 | echo<STATUS_OUTPUT> | ||
172 | ], | ||
173 | [<STATUS_DEFN>]) | ||
174 | |||
175 | =item F<modules/*/module.ac> | ||
176 | |||
177 | This file is optional. If present, it contains the B<autoconf> code for | ||
178 | that module, which is appended to the contents of the B<MODULES> variable | ||
179 | used for creating F<configure.ac>. | ||
180 | |||
181 | No macro substitutions are performed for that file. | ||
182 | |||
183 | Comment marker is B<##>. | ||
184 | |||
185 | The following comments starting with B<## module> are I<pragmatic> ones, | ||
186 | and are treated specially: | ||
187 | |||
188 | =over 8 | ||
189 | |||
190 | =item B<## module name: I<NAME>> | ||
191 | |||
192 | Use I<NAME> as module name when creating variable names for that module. This | ||
193 | is useful when the module name contains symbols that cannot be used in variable | ||
194 | names (as in, e.g. B<dict.org>). | ||
195 | |||
196 | =item B<## module description: I<TEXT>> | ||
197 | |||
198 | Use I<TEXT> as module description in B<STATUS_OUTPUT> (see F<stub.ac>). | ||
199 | |||
200 | =item B<## module category:> | ||
201 | |||
202 | Reserved for future use. | ||
203 | |||
204 | =back | ||
205 | |||
206 | As well as other B<##> comments, these comments do not appear in the output. | ||
207 | |||
208 | =item F<modules/stub.am> | ||
209 | |||
210 | Produces the file F<modules/Makefile.am>. Comment marker is B<##>. | ||
211 | |||
212 | Macro variables: | ||
213 | |||
214 | =over 8 | ||
215 | |||
216 | =item B<HEADING> | ||
217 | |||
218 | Same as in F<stub.ac>. | ||
219 | |||
220 | =item B<MODULES> | ||
221 | |||
222 | Produces B<Makefille.am> code for the B<SUBDIRS> variable. | ||
223 | |||
224 | =back | ||
225 | |||
226 | =item F<modules/template.c> | ||
227 | |||
228 | This template is used when B<-a> (B<--add>, B<--new>) option is given. | ||
229 | It produces the file F<modules/I<NAME>/I<NAME>.c>. Comment marker is B<//>. | ||
230 | |||
231 | Macro variables: | ||
232 | |||
233 | =over 8 | ||
234 | |||
235 | =item B<MODNAME> | ||
236 | |||
237 | Expands to the name of the module. | ||
238 | |||
239 | =back | ||
240 | |||
241 | =item F<modules/template.am> | ||
242 | |||
243 | This template is used when B<-a> (B<--add>, B<--new>) option is given. | ||
244 | It produces the file F<modules/I<NAME>/Makefile.am>. | ||
245 | |||
246 | Macro variables: | ||
247 | |||
248 | =over 8 | ||
249 | |||
250 | =item B<MODNAME> | ||
251 | |||
252 | Expands to the name of the module. | ||
253 | |||
254 | =back | ||
255 | |||
256 | =back | ||
257 | |||
258 | =head1 EXIT CODES | ||
259 | |||
260 | =over 4 | ||