Mercurial > gnulib

annotate doc/relocatable-maint.texi @ 40196:e63f5d3edab5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
relocatable-prog: Update documentation. * doc/relocatable-maint.texi (Supporting Relocation): Update to match the recent changes.
author Bruno Haible <bruno@clisp.org>
date Sun, 24 Feb 2019 01:49:15 +0100
parents a92075582b06
children 91454190d749
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
1 @node Supporting Relocation
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
2 @section Supporting Relocation
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
3
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
4 It has been a pain for many users of GNU packages for a long time that
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
5 packages are not relocatable. It means a user cannot copy a program,
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
6 installed by another user on the same machine, to his home directory,
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
7 and have it work correctly (including i18n). So many users need to go
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
8 through @code{configure; make; make install} with all its
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
9 dependencies, options, and hurdles.
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
10
17542
0479b39ae24c doc: Improve wording in relocatable-maint.texi.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13365
diff changeset
11 Red Hat, Debian, and other binary distributions solve the ``ease of
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
12 installation'' problem, but they hardwire path names, usually to
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
13 @file{/usr} or @file{/usr/local}. This means that users need root
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
14 privileges to install a binary package, and prevents installing two
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
15 different versions of the same binary package.
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
16
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
17 A relocatable program can be moved or copied to a different location
12152
64131ac8b004 relocatable: prefer 'file system' over 'filesystem'
Eric Blake <ebb9@byu.net>
parents: 11028
diff changeset
18 on the file system. It is possible to make symlinks to the installed
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
19 and moved programs, and invoke them through the symlink. It is
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
20 possible to do the same thing with a hard link @emph{only} if the hard
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
21 link file is in the same directory as the real program.
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
22
8315
b14a7aad863f Rename module 'relocatable' to 'relocatable-prog'.
Bruno Haible <bruno@clisp.org>
parents: 8281
diff changeset
23 The @code{relocatable-prog} module aims to ease the process of making a
b14a7aad863f Rename module 'relocatable' to 'relocatable-prog'.
Bruno Haible <bruno@clisp.org>
parents: 8281
diff changeset
24 GNU program relocatable. It helps overcome two obstacles. First, it aids
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
25 with relocating the hard-coded references to absolute file names that
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
26 GNU programs often contain. These references must be fixed up at
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
27 runtime if a program is to be successfully relocated. The
8315
b14a7aad863f Rename module 'relocatable' to 'relocatable-prog'.
Bruno Haible <bruno@clisp.org>
parents: 8281
diff changeset
28 @code{relocatable-prog} module provides a function @code{relocate} that
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
29 does this job.
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
30
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
31 Second, the loader must be able to find shared libraries linked to
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
32 relocatable executables or referenced by other shared libraries linked
8315
b14a7aad863f Rename module 'relocatable' to 'relocatable-prog'.
Bruno Haible <bruno@clisp.org>
parents: 8281
diff changeset
33 to relocatable executables. The @code{relocatable-prog} module helps out
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
34 here in a platform-specific way:
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
35
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
36 @itemize
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
37 @item
40196
e63f5d3edab5 relocatable-prog: Update documentation.
Bruno Haible <bruno@clisp.org>
parents: 40103
diff changeset
38 On most operating systems, it adds a linker option (@option{-rpath}) that
e63f5d3edab5 relocatable-prog: Update documentation.
Bruno Haible <bruno@clisp.org>
parents: 40103
diff changeset
39 causes the dynamic linker to search for libraries in a directory relative
e63f5d3edab5 relocatable-prog: Update documentation.
Bruno Haible <bruno@clisp.org>
parents: 40103
diff changeset
40 to the location of the invoked executable. This works on GNU/Linux and
e63f5d3edab5 relocatable-prog: Update documentation.
Bruno Haible <bruno@clisp.org>
parents: 40103
diff changeset
41 modern versions of FreeBSD, NetBSD, OpenBSD, Solaris, Haiku.
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
42
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
43 @item
40196
e63f5d3edab5 relocatable-prog: Update documentation.
Bruno Haible <bruno@clisp.org>
parents: 40103
diff changeset
44 On macOS, it modifies the installed executables after installation in a way
e63f5d3edab5 relocatable-prog: Update documentation.
Bruno Haible <bruno@clisp.org>
parents: 40103
diff changeset
45 that causes the dynamic linker to search for libraries in a directory relative
e63f5d3edab5 relocatable-prog: Update documentation.
Bruno Haible <bruno@clisp.org>
parents: 40103
diff changeset
46 to the location of the invoked executable.
e63f5d3edab5 relocatable-prog: Update documentation.
Bruno Haible <bruno@clisp.org>
parents: 40103
diff changeset
47
e63f5d3edab5 relocatable-prog: Update documentation.
Bruno Haible <bruno@clisp.org>
parents: 40103
diff changeset
48 @item
e63f5d3edab5 relocatable-prog: Update documentation.
Bruno Haible <bruno@clisp.org>
parents: 40103
diff changeset
49 On other Unix systems, it installs a trampoline executable. The trampoline
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
50 sets the environment variable that controls shared library searching
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
51 (usually @env{LD_LIBRARY_PATH}) and then invokes the real executable.
40196
e63f5d3edab5 relocatable-prog: Update documentation.
Bruno Haible <bruno@clisp.org>
parents: 40103
diff changeset
52 This applies to operating systems such as AIX, HP-UX, or Minix.
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
53
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
54 @item
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
55 On Windows, the executable's own directory is searched for libraries,
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
56 so installing shared libraries into the executable's directory is
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
57 sufficient.
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
58 @end itemize
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
59
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
60 You can make your program relocatable by following these steps:
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
61
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
62 @enumerate
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
63 @item
19023
d0be4dc17cdd relocatable-lib{,-lgpl}: improve documentation
Reuben Thomas <rrt@sc3d.org>
parents: 18917
diff changeset
64 Import the @code{relocatable-prog} module. For libraries, use the
d0be4dc17cdd relocatable-lib{,-lgpl}: improve documentation
Reuben Thomas <rrt@sc3d.org>
parents: 18917
diff changeset
65 @code{relocatable-lib} or @code{relocatable-lib-lgpl} module.
19469
f8e072011af8 doc: Improve explanation of supporting relocatable libraries.
Reuben Thomas <rrt@sc3d.org>
parents: 19023
diff changeset
66 If you need more than one module, or you need to use them with different
f8e072011af8 doc: Improve explanation of supporting relocatable libraries.
Reuben Thomas <rrt@sc3d.org>
parents: 19023
diff changeset
67 settings, you will need multiple copies of gnulib (@pxref{Multiple instances}).
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
68
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
69 @item
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
70 In every program, add to @code{main} as the first statement (even
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
71 before setting the locale or doing anything related to libintl):
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
72
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
73 @example
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
74 set_program_name (argv[0]);
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
75 @end example
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
76
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
77 The prototype for this function is in @file{progname.h}.
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
78
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
79 @item
19023
d0be4dc17cdd relocatable-lib{,-lgpl}: improve documentation
Reuben Thomas <rrt@sc3d.org>
parents: 18917
diff changeset
80 If you want your code to be portable to platforms that do not support
d0be4dc17cdd relocatable-lib{,-lgpl}: improve documentation
Reuben Thomas <rrt@sc3d.org>
parents: 18917
diff changeset
81 automatic initialization, call @code{set_relocation_prefix}.
d0be4dc17cdd relocatable-lib{,-lgpl}: improve documentation
Reuben Thomas <rrt@sc3d.org>
parents: 18917
diff changeset
82
d0be4dc17cdd relocatable-lib{,-lgpl}: improve documentation
Reuben Thomas <rrt@sc3d.org>
parents: 18917
diff changeset
83 @item
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
84 Everywhere where you use a constant pathname from installation-time,
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
85 wrap it in @code{relocate} so it gets translated to the run-time situation.
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
86 Example:
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
87
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
88 @example
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
89 bindtextdomain (PACKAGE, LOCALEDIR);
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
90 @end example
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
91
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
92 @noindent
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
93 becomes:
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
94
10095
60ed1a52905e remove trailing blanks
Jim Meyering <meyering@redhat.com>
parents: 8477
diff changeset
95 @example
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
96 bindtextdomain (PACKAGE, relocate (LOCALEDIR));
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
97 @end example
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
98
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
99 The prototype for this function is in @file{relocatable.h}.
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
100
18917
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 17597
diff changeset
101 There is also a variant of this function, named @code{relocate2}, that
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 17597
diff changeset
102 makes it easy to reclaim the memory allocated by the call.
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 17597
diff changeset
103
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
104 @item
13365
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
105 The @code{set_program_name} function can also configure some
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
106 additional libraries to relocate files that they access, by defining
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
107 corresponding C preprocessor symbols to 1. The libraries for which
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
108 this is supported and the corresponding preprocessor symbols are:
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
109
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
110 @table @asis
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
111 @item libcharset
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
112 @code{DEPENDS_ON_LIBCHARSET}
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
113
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
114 @item libiconv
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
115 @code{DEPENDS_ON_LIBICONV}
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
116
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
117 @item libintl
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
118 @code{DEPENDS_ON_LIBINTL}
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
119 @end table
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
120
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
121 Defining the symbol for a library makes every program in the package
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
122 depend on that library, whether the program really uses the library or
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
123 not, so this feature should be used with some caution.
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
124
09288814c405 Update maintainer documentation for 'relocatable-prog' module.
Ben Pfaff <blp@cs.stanford.edu>
parents: 13248
diff changeset
125 @item
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
126 If your package installs shell scripts, also import the
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
127 @code{relocatable-script} module. Then, near the beginning of each
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
128 shell script that your package installs, add the following:
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
129
39751
9b497a01631e doc: Avoid some overfull lines in the TeX output.
Werner LEMBERG <wl@gnu.org>
parents: 19469
diff changeset
130 @smallexample
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
131 @@relocatable_sh@@
40103
a92075582b06 relocatable: improve documentation
Akim Demaille <akim.demaille@gmail.com>
parents: 39751
diff changeset
132
a92075582b06 relocatable: improve documentation
Akim Demaille <akim.demaille@gmail.com>
parents: 39751
diff changeset
133 prefix="@@prefix@@"
a92075582b06 relocatable: improve documentation
Akim Demaille <akim.demaille@gmail.com>
parents: 39751
diff changeset
134 exec_prefix="@@exec_prefix@@" # usually needs $prefix.
a92075582b06 relocatable: improve documentation
Akim Demaille <akim.demaille@gmail.com>
parents: 39751
diff changeset
135 datarootdir="@@datarootdir@@" # usually needs $prefix.
a92075582b06 relocatable: improve documentation
Akim Demaille <akim.demaille@gmail.com>
parents: 39751
diff changeset
136
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
137 if test "@@RELOCATABLE@@" = yes; then
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
138 bindir="@@bindir@@"
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
139 orig_installdir="$bindir" # see Makefile.am's *_SCRIPTS variables
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
140 func_find_curr_installdir # determine curr_installdir
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
141 func_find_prefixes
17593
2e8cfcbe1d52 relocatable-shell: Update suggested usage in maintainer documentation.
Ben Pfaff <blp@cs.stanford.edu>
parents: 17542
diff changeset
142 relocate () @{
2e8cfcbe1d52 relocatable-shell: Update suggested usage in maintainer documentation.
Ben Pfaff <blp@cs.stanford.edu>
parents: 17542
diff changeset
143 echo "$1/" \
8477
0327e6475932 Break long line.
Bruno Haible <bruno@clisp.org>
parents: 8315
diff changeset
144 | sed -e "s%^$@{orig_installprefix@}/%$@{curr_installprefix@}/%" \
17593
2e8cfcbe1d52 relocatable-shell: Update suggested usage in maintainer documentation.
Ben Pfaff <blp@cs.stanford.edu>
parents: 17542
diff changeset
145 | sed -e 's,/$,,'
2e8cfcbe1d52 relocatable-shell: Update suggested usage in maintainer documentation.
Ben Pfaff <blp@cs.stanford.edu>
parents: 17542
diff changeset
146 @}
2e8cfcbe1d52 relocatable-shell: Update suggested usage in maintainer documentation.
Ben Pfaff <blp@cs.stanford.edu>
parents: 17542
diff changeset
147 else
2e8cfcbe1d52 relocatable-shell: Update suggested usage in maintainer documentation.
Ben Pfaff <blp@cs.stanford.edu>
parents: 17542
diff changeset
148 relocate () @{
2e8cfcbe1d52 relocatable-shell: Update suggested usage in maintainer documentation.
Ben Pfaff <blp@cs.stanford.edu>
parents: 17542
diff changeset
149 echo "$1"
2e8cfcbe1d52 relocatable-shell: Update suggested usage in maintainer documentation.
Ben Pfaff <blp@cs.stanford.edu>
parents: 17542
diff changeset
150 @}
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
151 fi
17593
2e8cfcbe1d52 relocatable-shell: Update suggested usage in maintainer documentation.
Ben Pfaff <blp@cs.stanford.edu>
parents: 17542
diff changeset
152
2e8cfcbe1d52 relocatable-shell: Update suggested usage in maintainer documentation.
Ben Pfaff <blp@cs.stanford.edu>
parents: 17542
diff changeset
153 # Get some relocated directory names.
40103
a92075582b06 relocatable: improve documentation
Akim Demaille <akim.demaille@gmail.com>
parents: 39751
diff changeset
154 sysconfdir=`relocate "@@sysconfdir@@"` # usually needs $prefix.
a92075582b06 relocatable: improve documentation
Akim Demaille <akim.demaille@gmail.com>
parents: 39751
diff changeset
155 some_datadir=`relocate "@@datadir@@/something"` # usually needs $datarootdir.
a92075582b06 relocatable: improve documentation
Akim Demaille <akim.demaille@gmail.com>
parents: 39751
diff changeset
156 bindir=`relocate "@@bindir@@"` # usually needs $exec_prefix, hence $prefix.
39751
9b497a01631e doc: Avoid some overfull lines in the TeX output.
Werner LEMBERG <wl@gnu.org>
parents: 19469
diff changeset
157 @end smallexample
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
158
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
159 You must adapt the definition of @code{orig_installdir}, depending on
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
160 where the script gets installed. Also, at the end, instead of
17593
2e8cfcbe1d52 relocatable-shell: Update suggested usage in maintainer documentation.
Ben Pfaff <blp@cs.stanford.edu>
parents: 17542
diff changeset
161 @code{sysconfdir} and @code{some_datadir}, transform those variables
2e8cfcbe1d52 relocatable-shell: Update suggested usage in maintainer documentation.
Ben Pfaff <blp@cs.stanford.edu>
parents: 17542
diff changeset
162 that you need.
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
163
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
164 @item
17594
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
165 If your package installs Perl scripts, also import the
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
166 @code{relocatable-perl} module. Then, near the beginning of each
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
167 Perl script that your package installs, add the following:
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
168
39751
9b497a01631e doc: Avoid some overfull lines in the TeX output.
Werner LEMBERG <wl@gnu.org>
parents: 19469
diff changeset
169 @smallexample
17594
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
170 @@relocatable_pl@@
17597
63e4133ca82e relocatable-maint.texi: escape braces
Daniel Albers <daniel@lbe.rs>
parents: 17594
diff changeset
171 if ("@@RELOCATABLE@@" eq "yes") @{
17594
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
172 my $exec_prefix = "@@exec_prefix@@";
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
173 my $orig_installdir = "@@bindir@@"; # see Makefile.am's *_SCRIPTS variables
39751
9b497a01631e doc: Avoid some overfull lines in the TeX output.
Werner LEMBERG <wl@gnu.org>
parents: 19469
diff changeset
174 my ($orig_installprefix, $curr_installprefix) =
9b497a01631e doc: Avoid some overfull lines in the TeX output.
Werner LEMBERG <wl@gnu.org>
parents: 19469
diff changeset
175 find_prefixes($orig_installdir, find_curr_installdir());
9b497a01631e doc: Avoid some overfull lines in the TeX output.
Werner LEMBERG <wl@gnu.org>
parents: 19469
diff changeset
176
9b497a01631e doc: Avoid some overfull lines in the TeX output.
Werner LEMBERG <wl@gnu.org>
parents: 19469
diff changeset
177 # the subroutine is defined whether or not the enclosing block is executed
9b497a01631e doc: Avoid some overfull lines in the TeX output.
Werner LEMBERG <wl@gnu.org>
parents: 19469
diff changeset
178 sub relocate @{
17594
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
179 my ($dir) = @@_;
17597
63e4133ca82e relocatable-maint.texi: escape braces
Daniel Albers <daniel@lbe.rs>
parents: 17594
diff changeset
180 if ("@@RELOCATABLE@@" eq "yes") @{
17594
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
181 $dir =~ s%^$orig_installprefix/%$curr_installprefix/%;
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
182 $dir =~ s,/$,,;
17597
63e4133ca82e relocatable-maint.texi: escape braces
Daniel Albers <daniel@lbe.rs>
parents: 17594
diff changeset
183 @}
17594
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
184 return $dir;
17597
63e4133ca82e relocatable-maint.texi: escape braces
Daniel Albers <daniel@lbe.rs>
parents: 17594
diff changeset
185 @}
63e4133ca82e relocatable-maint.texi: escape braces
Daniel Albers <daniel@lbe.rs>
parents: 17594
diff changeset
186 @}
17594
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
187
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
188 # Get some relocated directory names.
19023
d0be4dc17cdd relocatable-lib{,-lgpl}: improve documentation
Reuben Thomas <rrt@sc3d.org>
parents: 18917
diff changeset
189 # (The gnulib module 'configmake' can help with this.)
17594
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
190 $sysconfdir = relocate("@@sysconfdir@@");
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
191 $some_datadir = relocate(@@datadir@@/something");
39751
9b497a01631e doc: Avoid some overfull lines in the TeX output.
Werner LEMBERG <wl@gnu.org>
parents: 19469
diff changeset
192 @end smallexample
17594
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
193
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
194 You must adapt the definition of @code{$orig_installdir}, depending on
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
195 where the script gets installed. Also, at the end, instead of
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
196 @code{sysconfdir} and @code{some_datadir}, transform those variables
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
197 that you need.
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
198
23cb5b2fd95b relocatable-perl: like relocatable-script, but for Perl scripts
Reuben Thomas <rrt@sc3d.org>
parents: 17593
diff changeset
199 @item
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
200 In your @file{Makefile.am}, for every program @command{foo} that gets
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
201 installed in, say, @file{$(bindir)}, you add:
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
202
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
203 @example
8281
8dcf244ccec2 Recommend to set -D options in CPPFLAGS, not CFLAGS.
Bruno Haible <bruno@clisp.org>
parents: 8268
diff changeset
204 foo_CPPFLAGS = -DINSTALLDIR=\"$(bindir)\"
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
205 if RELOCATABLE_VIA_LD
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
206 foo_LDFLAGS = `$(RELOCATABLE_LDFLAGS) $(bindir)`
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
207 endif
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
208 @end example
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
209
19469
f8e072011af8 doc: Improve explanation of supporting relocatable libraries.
Reuben Thomas <rrt@sc3d.org>
parents: 19023
diff changeset
210 When building gnulib to use with a relocatable library, you need to
f8e072011af8 doc: Improve explanation of supporting relocatable libraries.
Reuben Thomas <rrt@sc3d.org>
parents: 19023
diff changeset
211 define the preprocessor symbol @code{IN_LIBRARY}.
f8e072011af8 doc: Improve explanation of supporting relocatable libraries.
Reuben Thomas <rrt@sc3d.org>
parents: 19023
diff changeset
212 You may also want to build with @code{ENABLE_COSTLY_RELOCATABLE}, in which case
f8e072011af8 doc: Improve explanation of supporting relocatable libraries.
Reuben Thomas <rrt@sc3d.org>
parents: 19023
diff changeset
213 you will also need to define @code{INSTALLDIR}.
f8e072011af8 doc: Improve explanation of supporting relocatable libraries.
Reuben Thomas <rrt@sc3d.org>
parents: 19023
diff changeset
214 The following fragment can be added to an override @code{Makefile.am} used
f8e072011af8 doc: Improve explanation of supporting relocatable libraries.
Reuben Thomas <rrt@sc3d.org>
parents: 19023
diff changeset
215 to build gnulib (@pxref{Modified build rules}).
19023
d0be4dc17cdd relocatable-lib{,-lgpl}: improve documentation
Reuben Thomas <rrt@sc3d.org>
parents: 18917
diff changeset
216
d0be4dc17cdd relocatable-lib{,-lgpl}: improve documentation
Reuben Thomas <rrt@sc3d.org>
parents: 18917
diff changeset
217 @example
19469
f8e072011af8 doc: Improve explanation of supporting relocatable libraries.
Reuben Thomas <rrt@sc3d.org>
parents: 19023
diff changeset
218 AM_CPPFLAGS += -DIN_LIBRARY -DENABLE_COSTLY_RELOCATABLE
f8e072011af8 doc: Improve explanation of supporting relocatable libraries.
Reuben Thomas <rrt@sc3d.org>
parents: 19023
diff changeset
219
f8e072011af8 doc: Improve explanation of supporting relocatable libraries.
Reuben Thomas <rrt@sc3d.org>
parents: 19023
diff changeset
220 if SHLIBS_IN_BINDIR
f8e072011af8 doc: Improve explanation of supporting relocatable libraries.
Reuben Thomas <rrt@sc3d.org>
parents: 19023
diff changeset
221 AM_CPPFLAGS += -DINSTALLDIR=\"$(bindir)\"
f8e072011af8 doc: Improve explanation of supporting relocatable libraries.
Reuben Thomas <rrt@sc3d.org>
parents: 19023
diff changeset
222 else
f8e072011af8 doc: Improve explanation of supporting relocatable libraries.
Reuben Thomas <rrt@sc3d.org>
parents: 19023
diff changeset
223 AM_CPPFLAGS += -DINSTALLDIR=\"$(libdir)\"
f8e072011af8 doc: Improve explanation of supporting relocatable libraries.
Reuben Thomas <rrt@sc3d.org>
parents: 19023
diff changeset
224 endif
19023
d0be4dc17cdd relocatable-lib{,-lgpl}: improve documentation
Reuben Thomas <rrt@sc3d.org>
parents: 18917
diff changeset
225 @end example
d0be4dc17cdd relocatable-lib{,-lgpl}: improve documentation
Reuben Thomas <rrt@sc3d.org>
parents: 18917
diff changeset
226
19469
f8e072011af8 doc: Improve explanation of supporting relocatable libraries.
Reuben Thomas <rrt@sc3d.org>
parents: 19023
diff changeset
227 @code{SHLIBS_IN_BINDIR} is defined in @file{configure.ac} as follows:
f8e072011af8 doc: Improve explanation of supporting relocatable libraries.
Reuben Thomas <rrt@sc3d.org>
parents: 19023
diff changeset
228
39751
9b497a01631e doc: Avoid some overfull lines in the TeX output.
Werner LEMBERG <wl@gnu.org>
parents: 19469
diff changeset
229 @smallexample
9b497a01631e doc: Avoid some overfull lines in the TeX output.
Werner LEMBERG <wl@gnu.org>
parents: 19469
diff changeset
230 AM_CONDITIONAL([SHLIBS_IN_BINDIR],
9b497a01631e doc: Avoid some overfull lines in the TeX output.
Werner LEMBERG <wl@gnu.org>
parents: 19469
diff changeset
231 [case "$host_os" in mingw* | cygwin*) true;; *) false;; esac])
9b497a01631e doc: Avoid some overfull lines in the TeX output.
Werner LEMBERG <wl@gnu.org>
parents: 19469
diff changeset
232 @end smallexample
19023
d0be4dc17cdd relocatable-lib{,-lgpl}: improve documentation
Reuben Thomas <rrt@sc3d.org>
parents: 18917
diff changeset
233
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
234 @item
11028
29b9820e29f2 Support for stripping executables in --enable-relocatable.
Bruno Haible <bruno@clisp.org>
parents: 10095
diff changeset
235 You may also need to add a couple of variable assignments to your
10095
60ed1a52905e remove trailing blanks
Jim Meyering <meyering@redhat.com>
parents: 8477
diff changeset
236 @file{configure.ac}.
8268
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
237
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
238 If your package (or any package you rely on, e.g.@: gettext-runtime)
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
239 will be relocated together with a set of installed shared libraries,
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
240 then set @var{RELOCATABLE_LIBRARY_PATH} to a colon-separated list
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
241 of those libraries' directories, e.g.
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
242 @example
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
243 RELOCATABLE_LIBRARY_PATH='$(libdir)'
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
244 @end example
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
245
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
246 If your @file{config.h} is not in @file{$(top_builddir)}, then set
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
247 @var{RELOCATABLE_CONFIG_H_DIR} to its directory, e.g.
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
248 @example
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
249 RELOCATABLE_CONFIG_H_DIR='$(top_builddir)/src'
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
250 @end example
0024ab394786 Documentation of 'relocatable' module - for maintainers.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
251 @end enumerate