7 This file attempts to describe the processes we use to maintain libtool,
8 and is not part of a release distribution.
13 * If you incorporate a change from somebody on the net:
14 If it is a large change, you must make sure they have signed the
15 appropriate paperwork, and be sure to add their name and email
18 * If a change fixes a test, mention the test in the git log entry.
20 * If somebody reports a new bug, mention their name in the git log entry
21 and in the test case you write.
23 * The correct response to most actual bugs is to write a new test case
24 that demonstrates the bug. Then fix the bug, re-run the test suite,
25 and check everything in.
27 * Always run the testsuite after applying a patch:
28 make check syntax-check TESTSUITEFLAGS="--jobs=$(nproc)" -j$(nproc)
30 Ideally also verify the release process doesn't break:
31 make distcheck TESTSUITEFLAGS="--jobs=$(nproc)" -j$(nproc)
32 This will run check & syntax-check from above, but will take longer as
33 builds & tests in different configurations.
35 * Some files in the libtool package are not owned by libtool. These
36 files should never be edited here. These files are:
41 + gendocs_template_min
65 The ones that are important for a release can be updated by ensuring
66 gnulib is up-to-date, and running 'bootstrap' to recheck the links are
69 * Changes other than bug fixes must be mentioned in NEWS.
75 * When writing tests, make sure the link invocation (first argument to
76 AT_CHECK) is on a single line so that 'testsuite -x' displays the
77 whole thing. You can use m4_do or '[... ]dnl' to wrap long lines.
79 * Run tests in parallel with
80 make -k check TESTSUITEFLAGS="--jobs=$(nproc)"
81 liberally, on as many platforms as you can. Use as many compilers and
82 linkers you can. To run old and new testsuites separately, use:
83 make check TESTSUITEFLAGS=-V
86 * The gnulib module also provides some maintainer-focused tests that only
87 work when run from a git checkout.
90 * The new Autotest testsuite uses keywords to denote test features:
91 autoconf needs Autoconf
92 automake needs Automake
93 libltdl exercises the 'libltdl' library
94 libtool exercises the 'libtool' script
95 libtoolize exercises the 'libtoolize' script
96 recursive runs the suite recursively, with a modified
97 'libtool' script and with '-k libtool'
98 CXX F77 FC GCJ exercises a language other than C
104 * We've adopted the convention that exported Autoconf macros should be
105 named with a leading 'LT_' and be documented in the libtool manual.
106 Internal macros begin with '_LT_' if they are visible to aclocal, or
107 potentially part of an AC_DEFUN/AC_REQUIRE path, or else '_lt_' if
108 they are very low level. This convention was only introduced just
109 before libtool-2.0, so there may still be exceptions in the existing
110 code. But all new code should use it.
112 * All shell variables used internally by libtool's Autoconf macros
113 should be named with the a leading 'lt_' (not that they cannot clash
114 with the '_lt_' macro namespace).
120 * ChangeLog is generated from git log messages, so you have to format
121 the git log carefully. Use --author for the (first, main) author
122 of changesets from others, and sign patches you have reviewed. If the
123 changeset has additional authors that need to be mentioned in the
124 generated ChangeLog, then add them to the git log message with:
126 Co-authored-by: A U Thor <email@example.com>
128 Similarly, if the ChangeLog will need a '(tiny change)' annotation,
129 then you should indicate that in the git log message with:
131 Copyright-paperwork-exempt: Yes
133 Start the git log message with a short one line summary, then an empty
134 line, then the rest of the log entry.
136 If you forgot to annotate correctly in the git log message, or made
137 any other mistake that needs correcting in the distributed ChangeLog
138 file, make an amendment against the SHA1 of the errored commit in
139 $aux_dir/git-log-fix.
141 * You may find it useful to install the $aux_dir/git-hooks/commit-msg
142 script to .git/hooks in your libtool working directory to help you
143 make the best use of git log message metadata.
145 * Do not ever rewind the public master branch nor any public release
146 branch on savannah, neither any release tags once they have been
147 published. Other branches and tags may have different rules.
149 * Avoid merge commits on the master branch of the public git repository.
150 For unpublished changes in your development tree, it's easiest to
151 rebase against the current master before applying them, this preserves
155 6. Editing '.am' Files
156 ======================
158 * Always use $(...) and not ${...}.
160 * Use ':', not 'true'. Use 'exit 1', not 'false'.
162 * Use '##' comments liberally. Comment anything even remotely unusual.
164 * Never use basename or dirname. Instead use sed.
166 * Do not use 'cd' within back-quotes, use '$(lt__cd)' instead.
167 Otherwise the directory name may be printed, depending on CDPATH.
169 * In general, if a loop is required, it should be silent. Then the body
170 of the loop itself should print each "important" command it runs.
172 * Use 4 extra spaces to indent continued dependencies.
174 * One needs to remember that for our whole logic for the different
175 libltdl modes to function correctly, the thing we need to ensure
176 *before the client runs libtoolize*, is that the subpackage case is
177 correct (because all files may be symlinked there). All others can
178 and will be fixed in the 'libtoolize --ltdl --(non)recursive' stage.
181 7. Editing '.m4' Files
182 ======================
184 * Be careful with both 'echo' and '$ECHO'. As the latter may be one of
188 it may not have more than one argument and its value may not be
189 eval'ed. However, the argument may start with a '-' and contain
190 backslashes. As a rule of thumb, use
191 echo .. for literal (constant) strings without leading
192 hyphen and no backslashes within,
193 $ECHO ".." otherwise.
194 func_echo_all when multiple arguments are present, or when
195 placed in an eval'ed variable.
197 * The Autoconf manual says that giving an empty parameter is equivalent
198 to not giving it at all. (In particular, the Autoconf manual doesn't
199 explain that "FOO()" is calling macro FOO with one empty parameter.)
200 To prevent misunderstanding, we should use m4_ifval to check whether
201 a parameter is empty, and not $# to check for the number of parameters.
203 * Any time we add a macro to an older version, lt~obsolete.m4 needs to
204 be updated in all newer versions.
207 8. Abstraction layers in libltdl
208 ================================
210 * The libltdl API uses a layered approach to differentiate internal and
211 external interfaces, among other things. To keep the abstraction
212 consistent, files in a given layer may only use APIs from files in the
213 lower layers. The ASCII art boxes below represent this stack, from
216 * But first, outside of the stack, there is a convenience header that
217 defines the internal interfaces (as evidenced by the 'lt__' prefix to
218 the filename!) shared between implementation files in the stack, that
219 are however not exported to libltdl clients:
225 * The top layer of the stack is the libltdl API proper, which includes
226 the relevant subsystems automatically. Clients of libltdl need only
237 * The next layer is comprised of the subsystems of the exported libltdl
238 API, which are implemented by files that are named with a leading 'lt_'
239 (single underscore!):
241 ,------------v---------------.
242 | lt_error.h | lt_dlloader.h |
243 +------------+---------------+
244 | lt_error.c | lt_dlloader.c |
245 `------------^---------------'
247 * The next file is used both by the headers that implement it (in which
248 case its function is to avoid namespace clashes when linking with the
249 GNU C library proper) and is included by code that wants to program
250 against a glibc-like interface, in which case it serves to pull in all
251 the glibc-like functionality used by libltdl with a simple:
253 #include <libltdl/lt__glibc.h>
255 It consists of a single file:
261 * Next to last is the libc abstraction layer, which provides a uniform
262 API to various system libc interfaces that differ between hosts
263 supported by libtool. Typically, the files that implement this layer
266 #if defined(LT_CONFIG_H)
267 # include LT_CONFIG_H
271 #include "lt_system.h"
273 Or if they are installed headers that must work outside the libtool
276 #include <libltdl/lt_system.h>
278 This layer's interface is defined by files that are usually named with
281 ,--------------v-------------v------------v--------v---------.
282 | lt__dirent.h | lt__alloc.h | lt__strl.h | argz.h | slist.h |
283 +--------------+-------------+------------+--------+---------+
284 | lt__dirent.c | lt__alloc.c | lt__strl.c | argz.c | slist.c |
285 `--------------^-------------^------------^--------^---------'
287 (argz.h and slist.h are used independently of libltdl in other projects)
289 * At the bottom of the stack we have the system abstraction layer,
290 which tries to smooth over the cracks where there are differences
291 between host systems and compilers. config.h is generated at
292 configure time and is not installed; lt_system.h is an installed
293 file and cannot use macros from config.h:
303 * Tacked on the side of this stack, attached via the lt_dlloader.h
304 definitions are the various implementation modules for run-time module
305 loading: preopen.c, dlopen.c etc.
311 GNU Libtool uses 3 different licenses for the files distributed herein,
312 with several variations on license text. It is important that you use
313 the correct license text in each new file added. Here are the texts
314 along with some notes on when each is appropriate. Appropriate
315 commenting (shell, C etc) and decoration (m4 etc) assumed throughout.
319 9.1. Notice preservation
321 Autoconf macros and files used to generate them need this license, along
322 with files such as HACKING, NEWS, README, README.alpha, TODO and
325 Copyright (C) <year list> Free Software Foundation, Inc.
326 Written by <author>, <year>
328 Copying and distribution of this file, with or without modification,
329 are permitted in any medium without royalty provided the copyright
330 notice and this notice are preserved. This file is offered as-is,
331 without warranty of any kind.
337 Everything else in the distribution has the following license text
338 unless there is good reason to use one of the other license texts
341 Copyright (C) <year list> Free Software Foundation, Inc.
342 Written by <author>, <year>
344 This file is part of GNU Libtool.
346 GNU Libtool is free software; you can redistribute it and/or
347 modify it under the terms of the GNU General Public License as
348 published by the Free Software Foundation; either version 2 of
349 the License, or (at your option) any later version.
351 GNU Libtool is distributed in the hope that it will be useful,
352 but WITHOUT ANY WARRANTY; without even the implied warranty of
353 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
354 GNU General Public License for more details.
356 You should have received a copy of the GNU General Public License
357 along with GNU Libtool; see the file COPYING. If not, a copy
358 can be downloaded from http://www.gnu.org/licenses/gpl.html,
359 or obtained by writing to the Free Software Foundation, Inc.,
360 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
364 9.3. GPL with self extracting version
366 Some of the sources built atop the options-parser framework use
367 func_version() to extract their --version output from the copyright
368 block. Those files also need the --version copyright text paragraph as
371 <program name> (GNU @PACKAGE@) <version number>
372 Written by <author> <email address>.
374 This file is part of <parent package name>.
376 Copyright (C) <year list> Free Software Foundation, Inc.
377 This is free software; see the source for copying conditions. There is NO
378 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
380 <program name> is free software; you can redistribute it and/or modify
381 it under the terms of the GNU General Public License as published by
382 the Free Software Foundation; either version 2 of the License, or
383 (at your option) any later version.
385 <program name> is distributed in the hope that it will be useful, but
386 WITHOUT ANY WARRANTY; without even the implied warranty of
387 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
388 GNU General Public License for more details.
390 You should have received a copy of the GNU General Public License
391 along with <program name>; see the file COPYING. If not, a copy
392 can be downloaded from http://www.gnu.org/licenses/gpl.html,
393 or obtained by writing to the Free Software Foundation, Inc.,
394 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
398 9.4. GPL with self extracting version and Libtool exception clause
400 Although the libtool script is generated from 'ltmain.in' according
401 to the rules in the preceding subsection, it also needs the Libtool
402 exception clause so that it can be redistributed by other projects
405 <program name> (GNU @PACKAGE@@TIMESTAMP@) <version number>
406 Written by <author> <email address>.
408 This file is part of GNU Libtool.
410 Copyright (C) <year list> Free Software Foundation, Inc.
411 This is free software; see the source for copying conditions. There is NO
412 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
414 <program name> is free software; you can redistribute it and/or modify
415 it under the terms of the GNU General Public License as published by
416 the Free Software Foundation; either version 2 of the License, or
417 (at your option) any later version.
419 As a special exception to the GNU General Public License,
420 if you distribute this file as part of a program or library that
421 is built using GNU Libtool, you may include this file under the
422 same distribution terms that you use for the rest of that program.
424 <program name> is distributed in the hope that it will be useful, but
425 WITHOUT ANY WARRANTY; without even the implied warranty of
426 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
427 GNU General Public License for more details.
429 You should have received a copy of the GNU General Public License
430 along with <program name>; see the file COPYING. If not, a copy
431 can be downloaded from http://www.gnu.org/licenses/gpl.html,
432 or obtained by writing to the Free Software Foundation, Inc.,
433 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
437 9.5. LGPL with Libtool exception clause
439 Finally, not only is Libltdl is LGPLed, but it is routinely
440 redistributed inside projects that use it, so its sources need to use
441 the following license text citing the LGPL along with Libtool's special
444 Copyright (C) <year list> Free Software Foundation, Inc.
445 Written by <author>, <year>
447 NOTE: The canonical source of this file is maintained with the
448 GNU Libtool package. Report bugs to bug-libtool@gnu.org.
450 GNU Libltdl is free software; you can redistribute it and/or
451 modify it under the terms of the GNU Lesser General Public
452 License as published by the Free Software Foundation; either
453 version 2 of the License, or (at your option) any later version.
455 As a special exception to the GNU Lesser General Public License,
456 if you distribute this file as part of a program or library that
457 is built using GNU Libtool, you may include this file under the
458 same distribution terms that you use for the rest of that program.
460 GNU Libltdl is distributed in the hope that it will be useful,
461 but WITHOUT ANY WARRANTY; without even the implied warranty of
462 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
463 GNU Lesser General Public License for more details.
465 You should have received a copy of the GNU Lesser General Public
466 License along with GNU Libltdl; see the file COPYING.LIB. If not, a
467 copy can be downloaded from http://www.gnu.org/licenses/lgpl.html,
468 or obtained by writing to the Free Software Foundation, Inc.,
469 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
472 Copyright (C) 2004-2008, 2010-2019, 2021-2024 Free Software
474 Written by Gary V. Vaughan, 2004
476 This file is part of GNU Libtool.
478 Copying and distribution of this file, with or without modification,
479 are permitted in any medium without royalty provided the copyright
480 notice and this notice are preserved. This file is offered as-is,
481 without warranty of any kind.