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 * To debug a failing or skipped range of tests, e.g. 13 to 14:
80 make check-local TESTSUITEFLAGS="--debug 13-14"
81 More generally, in the TESTSUITEFLAGS you can use the documented
82 options for Autotest generated testsuites:
83 https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.72/html_node/testsuite-Invocation.html
85 * Run tests in parallel with
86 make -k check TESTSUITEFLAGS="--jobs=$(nproc)"
87 liberally, on as many platforms as you can. Use as many compilers and
88 linkers you can. To run old and new testsuites separately, use:
89 make check TESTSUITEFLAGS=-V
92 * The gnulib module also provides some maintainer-focused tests that only
93 work when run from a git checkout.
96 * The new Autotest testsuite uses keywords to denote test features:
97 autoconf needs Autoconf
98 automake needs Automake
99 libltdl exercises the 'libltdl' library
100 libtool exercises the 'libtool' script
101 libtoolize exercises the 'libtoolize' script
102 recursive runs the suite recursively, with a modified
103 'libtool' script and with '-k libtool'
104 CXX F77 FC GCJ exercises a language other than C
110 * We've adopted the convention that exported Autoconf macros should be
111 named with a leading 'LT_' and be documented in the libtool manual.
112 Internal macros begin with '_LT_' if they are visible to aclocal, or
113 potentially part of an AC_DEFUN/AC_REQUIRE path, or else '_lt_' if
114 they are very low level. This convention was only introduced just
115 before libtool-2.0, so there may still be exceptions in the existing
116 code. But all new code should use it.
118 * All shell variables used internally by libtool's Autoconf macros
119 should be named with the a leading 'lt_' (not that they cannot clash
120 with the '_lt_' macro namespace).
126 * ChangeLog is generated from git log messages, so you have to format
127 the git log carefully. Use --author for the (first, main) author
128 of changesets from others, and sign patches you have reviewed. If the
129 changeset has additional authors that need to be mentioned in the
130 generated ChangeLog, then add them to the git log message with:
132 Co-authored-by: A U Thor <email@example.com>
134 Similarly, if the ChangeLog will need a '(tiny change)' annotation,
135 then you should indicate that in the git log message with:
137 Copyright-paperwork-exempt: Yes
139 Start the git log message with a short one line summary, then an empty
140 line, then the rest of the log entry.
142 If you forgot to annotate correctly in the git log message, or made
143 any other mistake that needs correcting in the distributed ChangeLog
144 file, make an amendment against the SHA1 of the errored commit in
145 $aux_dir/git-log-fix.
147 * You may find it useful to install the $aux_dir/git-hooks/commit-msg
148 script to .git/hooks in your libtool working directory to help you
149 make the best use of git log message metadata.
151 * Do not ever rewind the public master branch nor any public release
152 branch on savannah, neither any release tags once they have been
153 published. Other branches and tags may have different rules.
155 * Avoid merge commits on the master branch of the public git repository.
156 For unpublished changes in your development tree, it's easiest to
157 rebase against the current master before applying them, this preserves
161 6. Editing '.am' Files
162 ======================
164 * Always use $(...) and not ${...}.
166 * Use ':', not 'true'. Use 'exit 1', not 'false'.
168 * Use '##' comments liberally. Comment anything even remotely unusual.
170 * Never use basename or dirname. Instead use sed.
172 * Do not use 'cd' within back-quotes, use '$(lt__cd)' instead.
173 Otherwise the directory name may be printed, depending on CDPATH.
175 * In general, if a loop is required, it should be silent. Then the body
176 of the loop itself should print each "important" command it runs.
178 * Use 4 extra spaces to indent continued dependencies.
180 * One needs to remember that for our whole logic for the different
181 libltdl modes to function correctly, the thing we need to ensure
182 *before the client runs libtoolize*, is that the subpackage case is
183 correct (because all files may be symlinked there). All others can
184 and will be fixed in the 'libtoolize --ltdl --(non)recursive' stage.
187 7. Editing '.m4' Files
188 ======================
190 * Be careful with both 'echo' and '$ECHO'. As the latter may be one of
194 it may not have more than one argument and its value may not be
195 eval'ed. However, the argument may start with a '-' and contain
196 backslashes. As a rule of thumb, use
197 echo .. for literal (constant) strings without leading
198 hyphen and no backslashes within,
199 $ECHO ".." otherwise.
200 func_echo_all when multiple arguments are present, or when
201 placed in an eval'ed variable.
203 * The Autoconf manual says that giving an empty parameter is equivalent
204 to not giving it at all. (In particular, the Autoconf manual doesn't
205 explain that "FOO()" is calling macro FOO with one empty parameter.)
206 To prevent misunderstanding, we should use m4_ifval to check whether
207 a parameter is empty, and not $# to check for the number of parameters.
209 * Any time we add a macro to an older version, lt~obsolete.m4 needs to
210 be updated in all newer versions.
213 8. Abstraction layers in libltdl
214 ================================
216 * The libltdl API uses a layered approach to differentiate internal and
217 external interfaces, among other things. To keep the abstraction
218 consistent, files in a given layer may only use APIs from files in the
219 lower layers. The ASCII art boxes below represent this stack, from
222 * But first, outside of the stack, there is a convenience header that
223 defines the internal interfaces (as evidenced by the 'lt__' prefix to
224 the filename!) shared between implementation files in the stack, that
225 are however not exported to libltdl clients:
231 * The top layer of the stack is the libltdl API proper, which includes
232 the relevant subsystems automatically. Clients of libltdl need only
243 * The next layer is comprised of the subsystems of the exported libltdl
244 API, which are implemented by files that are named with a leading 'lt_'
245 (single underscore!):
247 ,------------v---------------.
248 | lt_error.h | lt_dlloader.h |
249 +------------+---------------+
250 | lt_error.c | lt_dlloader.c |
251 `------------^---------------'
253 * The next file is used both by the headers that implement it (in which
254 case its function is to avoid namespace clashes when linking with the
255 GNU C library proper) and is included by code that wants to program
256 against a glibc-like interface, in which case it serves to pull in all
257 the glibc-like functionality used by libltdl with a simple:
259 #include <libltdl/lt__glibc.h>
261 It consists of a single file:
267 * Next to last is the libc abstraction layer, which provides a uniform
268 API to various system libc interfaces that differ between hosts
269 supported by libtool. Typically, the files that implement this layer
272 #if defined(LT_CONFIG_H)
273 # include LT_CONFIG_H
277 #include "lt_system.h"
279 Or if they are installed headers that must work outside the libtool
282 #include <libltdl/lt_system.h>
284 This layer's interface is defined by files that are usually named with
287 ,--------------v-------------v------------v--------v---------.
288 | lt__dirent.h | lt__alloc.h | lt__strl.h | argz.h | slist.h |
289 +--------------+-------------+------------+--------+---------+
290 | lt__dirent.c | lt__alloc.c | lt__strl.c | argz.c | slist.c |
291 `--------------^-------------^------------^--------^---------'
293 (argz.h and slist.h are used independently of libltdl in other projects)
295 * At the bottom of the stack we have the system abstraction layer,
296 which tries to smooth over the cracks where there are differences
297 between host systems and compilers. config.h is generated at
298 configure time and is not installed; lt_system.h is an installed
299 file and cannot use macros from config.h:
309 * Tacked on the side of this stack, attached via the lt_dlloader.h
310 definitions are the various implementation modules for run-time module
311 loading: preopen.c, dlopen.c etc.
317 GNU Libtool uses 3 different licenses for the files distributed herein,
318 with several variations on license text. It is important that you use
319 the correct license text in each new file added. Here are the texts
320 along with some notes on when each is appropriate. Appropriate
321 commenting (shell, C etc) and decoration (m4 etc) assumed throughout.
325 9.1. Notice preservation
327 Autoconf macros and files used to generate them need this license, along
328 with files such as HACKING, NEWS, README, README.alpha, TODO and
331 Copyright (C) <year list> Free Software Foundation, Inc.
332 Written by <author>, <year>
334 Copying and distribution of this file, with or without modification,
335 are permitted in any medium without royalty provided the copyright
336 notice and this notice are preserved. This file is offered as-is,
337 without warranty of any kind.
343 Everything else in the distribution has the following license text
344 unless there is good reason to use one of the other license texts
347 Copyright (C) <year list> Free Software Foundation, Inc.
348 Written by <author>, <year>
350 This file is part of GNU Libtool.
352 GNU Libtool is free software; you can redistribute it and/or
353 modify it under the terms of the GNU General Public License as
354 published by the Free Software Foundation; either version 2 of
355 the License, or (at your option) any later version.
357 GNU Libtool is distributed in the hope that it will be useful,
358 but WITHOUT ANY WARRANTY; without even the implied warranty of
359 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
360 GNU General Public License for more details.
362 You should have received a copy of the GNU General Public License
363 along with GNU Libtool; see the file COPYING. If not, a copy
364 can be downloaded from http://www.gnu.org/licenses/gpl.html,
365 or obtained by writing to the Free Software Foundation, Inc.,
366 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
370 9.3. GPL with self extracting version
372 Some of the sources built atop the options-parser framework use
373 func_version() to extract their --version output from the copyright
374 block. Those files also need the --version copyright text paragraph as
377 <program name> (GNU @PACKAGE@) <version number>
378 Written by <author> <email address>.
380 This file is part of <parent package name>.
382 Copyright (C) <year list> Free Software Foundation, Inc.
383 This is free software; see the source for copying conditions. There is NO
384 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
386 <program name> is free software; you can redistribute it and/or modify
387 it under the terms of the GNU General Public License as published by
388 the Free Software Foundation; either version 2 of the License, or
389 (at your option) any later version.
391 <program name> is distributed in the hope that it will be useful, but
392 WITHOUT ANY WARRANTY; without even the implied warranty of
393 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
394 GNU General Public License for more details.
396 You should have received a copy of the GNU General Public License
397 along with <program name>; see the file COPYING. If not, a copy
398 can be downloaded from http://www.gnu.org/licenses/gpl.html,
399 or obtained by writing to the Free Software Foundation, Inc.,
400 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
404 9.4. GPL with self extracting version and Libtool exception clause
406 Although the libtool script is generated from 'ltmain.in' according
407 to the rules in the preceding subsection, it also needs the Libtool
408 exception clause so that it can be redistributed by other projects
411 <program name> (GNU @PACKAGE@@TIMESTAMP@) <version number>
412 Written by <author> <email address>.
414 This file is part of GNU Libtool.
416 Copyright (C) <year list> Free Software Foundation, Inc.
417 This is free software; see the source for copying conditions. There is NO
418 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
420 <program name> is free software; you can redistribute it and/or modify
421 it under the terms of the GNU General Public License as published by
422 the Free Software Foundation; either version 2 of the License, or
423 (at your option) any later version.
425 As a special exception to the GNU General Public License,
426 if you distribute this file as part of a program or library that
427 is built using GNU Libtool, you may include this file under the
428 same distribution terms that you use for the rest of that program.
430 <program name> is distributed in the hope that it will be useful, but
431 WITHOUT ANY WARRANTY; without even the implied warranty of
432 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
433 GNU General Public License for more details.
435 You should have received a copy of the GNU General Public License
436 along with <program name>; see the file COPYING. If not, a copy
437 can be downloaded from http://www.gnu.org/licenses/gpl.html,
438 or obtained by writing to the Free Software Foundation, Inc.,
439 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
443 9.5. LGPL with Libtool exception clause
445 Finally, not only is Libltdl is LGPLed, but it is routinely
446 redistributed inside projects that use it, so its sources need to use
447 the following license text citing the LGPL along with Libtool's special
450 Copyright (C) <year list> Free Software Foundation, Inc.
451 Written by <author>, <year>
453 NOTE: The canonical source of this file is maintained with the
454 GNU Libtool package. Report bugs to bug-libtool@gnu.org.
456 GNU Libltdl is free software; you can redistribute it and/or
457 modify it under the terms of the GNU Lesser General Public
458 License as published by the Free Software Foundation; either
459 version 2 of the License, or (at your option) any later version.
461 As a special exception to the GNU Lesser General Public License,
462 if you distribute this file as part of a program or library that
463 is built using GNU Libtool, you may include this file under the
464 same distribution terms that you use for the rest of that program.
466 GNU Libltdl is distributed in the hope that it will be useful,
467 but WITHOUT ANY WARRANTY; without even the implied warranty of
468 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
469 GNU Lesser General Public License for more details.
471 You should have received a copy of the GNU Lesser General Public
472 License along with GNU Libltdl; see the file COPYING.LIB. If not, a
473 copy can be downloaded from http://www.gnu.org/licenses/lgpl.html,
474 or obtained by writing to the Free Software Foundation, Inc.,
475 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
478 Copyright (C) 2004-2008, 2010-2019, 2021-2024 Free Software
480 Written by Gary V. Vaughan, 2004
482 This file is part of GNU Libtool.
484 Copying and distribution of this file, with or without modification,
485 are permitted in any medium without royalty provided the copyright
486 notice and this notice are preserved. This file is offered as-is,
487 without warranty of any kind.