1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
|
# mm-common overview
The following sections provide an overview of the various files shipped
with mm-common, and briefly explain their purpose. Detailed documentation
and usage instructions can be found in the files themselves.
## mm-common-prepare and Autotools
The mm-common-prepare shell script is installed in ${bindir} and must be
invoked from the bootstrap script of a binding module in order to set up
necessary support files in the project's source tree. It should be run
before any of Autotools' own setup utilities. The classic command line
options such as --copy and --force can be used to adjust the behavior of
mm-common-prepare. A typical autogen.sh would look like this:
```
#! /bin/sh -e
test -n "$srcdir" || srcdir=`dirname "$0"`
test -n "$srcdir" || srcdir=.
mm-common-prepare --copy --force "$srcdir"
autoreconf --force --install --verbose "$srcdir"
test -n "$NOCONFIGURE" || "$srcdir/configure" --enable-maintainer-mode "$@"
```
Do not forget to set:
```
ACLOCAL_AMFLAGS = -I build ${ACLOCAL_FLAGS}
```
in your project's top-level Makefile.am. "build" should be changed to the
name of the Autoconf M4 macro subdirectory of your project's source tree.
Also note that mm-common-prepare inspects the project's configure.ac file
for the AC_CONFIG_AUX_DIR([...]) argument. This is explained in further
detail below in the section on Automake include files.
## mm-common-get and Meson
The mm-common-get shell script is installed in ${bindir} and must be
invoked with run_command() early in a meson.build file. The meson.build file
should contain code similar to
```
python3 = import('python').find_installation()
cmd_py = '''
import os
import sys
sys.exit(os.path.isdir("@0@") or os.path.isfile("@0@"))
'''.format(project_source_root / '.git')
is_git_build = run_command(python3, '-c', cmd_py, check: false).returncode() != 0
maintainer_mode_opt = get_option('maintainer-mode')
maintainer_mode = maintainer_mode_opt == 'true' or \
(maintainer_mode_opt == 'if-git-build' and is_git_build)
mm_common_get = find_program('mm-common-get', required: false)
if maintainer_mode and not mm_common_get.found()
message('Maintainer mode requires the \'mm-common-get\' command. If it is not found,\n' +
'install the \'mm-common\' package, version 1.0.0 or higher.')
# If meson --wrap-mode != forcefallback, Meson falls back to the mm-common
# subproject only if mm-common-get is required.
mm_common_get = find_program('mm-common-get', required: true)
endif
if maintainer_mode
# Copy files to untracked/build_scripts and untracked/docs.
run_command(mm_common_get, '--force',
project_source_root / 'untracked' / 'build_scripts',
project_source_root / 'untracked' / 'docs',
check: true,
)
endif
```
## Autoconf M4 macros (Autotools)
The Autoconf M4 macros are installed into the system-wide macro repository
in the ${datadir}/aclocal directory. Since all used M4 macros are copied
into aclocal.m4, these macro files are required only in maintainer-mode.
For this reason, they are not copied into the source tree of a project by
mm-common-prepare. If mm-common is installed to a different prefix than
Automake, it may be necessary to adjust ACLOCAL_PATH accordingly so that
aclocal can find the M4 files:
```
export ACLOCAL_PATH="${mm_common_prefix}/share/aclocal"
```
This step is not necessary when using jhbuild, as it takes care of setting
up the environment for using the locally built modules.
- macros/mm-common.m4: (generated from macros/mm-common.m4.in) \
Provides MM_PREREQ() for requiring a minimum version of mm-common, and
an internal initialization macro shared by the other mm-common macros.
- macros/mm-warnings.m4: \
Implements the MM_ARG_ENABLE_WARNINGS() Autoconf macro for easy setup
of compiler diagnostics through the --enable-warnings configure option.
- macros/mm-doc.m4: \
Implements the MM_ARG_ENABLE_DOCUMENTATION() Autoconf macro to initialize
the documentation support for a C++ binding package. Among other things,
it provides the --enable-documentation configure option, and checks for
the required utilities.
The other Autoconf macro defined here is MM_ARG_WITH_TAGFILE_DOC(), which
ties all the ends together in order to make cross-referencing to external
documentation work. This macro should be called once for each external
Doxygen tag file a binding package depends on. It implements a configure
option to override tag file locations, attempts automatic configuration
if possible, and takes care of building the list of tag files and their
default base paths for substitution into the configuration Doxyfile. It
also generates the command line options for doc-install.pl.
- macros/mm-module.m4: \
The magic MM_INIT_MODULE() macro takes care of defining the various
substitution variables and preprocessor macros to identify the name,
version and API version of a C++ binding module.
- macros/mm-pkg.m4: \
The helper macro MM_PKG_CONFIG_SUBST, which simplifies the retrieval of
specific configuration values from pkg-config. Checks for particular
utility programs are also defined here, such as MM_CHECK_GNU_MAKE and
MM_CHECK_PERL.
- macros/mm-dietlib.m4: \
Implements Autoconf macros which provide options intended to reduce the
binary size of the generated binding library, typically for embedded use.
The MM_PROG_GCC_VISIBILITY macro is defined in this file as well.
- macros/mm-ax_cxx_compile_stdcxx.m4: \
Implements the MM_AX_CXX_COMPILE_STDCXX() macro to test and set flags
for C++11/14/17 compatibility of the C++ compiler. This is identical to the
AX_CXX_COMPILE_STDCXX() macro described at
<http://www.gnu.org/software/autoconf-archive/ax_cxx_compile_stdcxx.html>,
except for the MM_ prefix.
## Automake include files (Autotools)
The Automake include files are located in the am_include/ directory.
The installed mm-common-prepare program copies all of the .am files into
a project's source tree. If AC_CONFIG_AUX_DIR([...]) is specified in
the configure.ac file, the .am files will be placed in the indicated
subdirectory.
- am_include/generate-binding.am: \
Variables and rules for running the gmmproc code generator to produce
the source code files for a C++ binding module.
- am_include/compile-binding.am: \
Variables and rules for compiling and linking the shared library which
implements a C++ binding module.
- am_include/doc-reference.am: \
Variables and rules for building the API reference documentation using
Doxygen, and to create a Devhelp book for the library. The installation
rules also take care of translating references to external documentation
in the generated hypertext documents.
- am_include/dist-changelog.am: \
A dist-hook rule to automatically generate a ChangeLog file when making
a release, intended to be used by modules which use the version control
log exclusively to document changes.
## Python build scripts (Meson)
These scripts can be called from meson.build files with run_command(),
custom_target(), meson.add_postconf_script(), meson.add_install_script()
and meson.add_dist_script().
- util/build_scripts/generate-binding.py: \
Commands for running the gmmproc code generator to produce
the source code files for a C++ binding module.
- util/build_scripts/doc-reference.py: \
Commands for building the API reference documentation using
Doxygen, and to create a Devhelp book for the library. The installation
rules also take care of translating references to external documentation
in the generated hypertext documents.
- util/build_scripts/dist-changelog.py: \
A git command to generate a ChangeLog file when making a release,
intended to be used by modules which use the version control
log exclusively to document changes.
- util/build_scripts/dist-build-scripts.py: \
Commands that trim the distribution directory before a tarball is made.
The scripts copied by mm-common-get are distributed, although they are
not checked into the git repository. All .gitignore files and an empty build/
directory are removed
- util/build_scripts/check-dllexport-usage.py: \
Command that checks on the gmmproc version that is to be used or has been used
to generate the sources, to check whether to use compiler directives to
export symbols. Only used for Visual Studio or clang-cl builds.
## Documentation utilities (Meson and Autotools)
These are two Perl scripts and two equivalent Python scripts, a style sheet,
and one XSL transformation which assist with the task of generating and installing
the Doxygen reference documentation. At least doc-install.pl or doc-install.py
is also required for tarball builds. Autotools uses the Perl scripts.
Meson uses the Python scripts.
Autotools: To avoid copying these files into all binding modules, they are
distributed and installed with the mm-common module. Those binding modules
which shall depend on mm-common only in maintainer-mode must call
MM_CONFIG_DOCTOOL_DIR([...]) in configure.ac to indicate to mm-common-prepare
that it should copy the documentation utilities into the project's source tree.
Otherwise the files installed with mm-common will be used automatically.
- util/doc-postprocess.pl: \
util/doc_postprocess.py: \
A simple script to post-process the HTML files generated by Doxygen.
It replaces various code constructs that do not match the coding style
used throughout the C++ bindings. For instance, it rewrites function
prototypes in order to place the reference symbol (&) next to the type
instead of the name of the argument.
- util/doc-install.pl: \
util/doc_install.py: \
A replacement for the installdox script generated by Doxygen. Its
purpose is to translate references to external documentation at the
time the documentation is installed. This step is necessary because
the documentation is included in the tarballs, and the location of
external documentation on the installation system is not known at the
time the documentation is generated.
Apart from replacing the functionality of installdox, doc-install.pl
also acts as a drop-in replacement for the classic BSD install command
for easy integration with Automake. It also translates Devhelp books
as well, and will happily pass through unrecognized files without any
alterations.
- util/doxygen.css: \
A Cascading Style Sheet to unify the appearance of the HTML reference
documentation generated by Doxygen for each C++ binding module.
This file is deprecated. Use util/doxygen-extra.css instead.
- util/doxygen-extra.css: \
A Cascading Style Sheet to unify the appearance of the HTML reference
documentation generated by Doxygen for each C++ binding module.
- util/tagfile-to-devhelp2.xsl: \
An XSLT script to generate a Devhelp2 book for the Doxygen reference
documentation. The generated Doxygen tag file serves as the input of
the translation.
## GNU C++ Library tag file
All modules in the GNOME C++ bindings set make use of the C++ standard
library in the API. As the GNU C++ Library shipped with GCC also uses
Doxygen for its reference documentation, its tag file is made available
by mm-common at a shared location for use by all C++ binding modules.
- doctags/libstdc++.tag: \
The Doxygen tag file for the GNU libstdc++ reference documentation
hosted at <http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/>.
This file is distributed with release archives of mm-common, but not
checked into version control on gnome.org. If mm-common is built with
Autotools in maintainer-mode or with Meson and use-network=true,
the file will be downloaded automatically from the gcc.gnu.org web server.
The file libstdc++.tag is installed into the package data directory
of mm-common. The mm-common-libstdc++ pkg-config module defines the
variables ${doxytagfile} and ${htmlrefpub}, which can be queried for
the location of the tag file and the URL of the online documentation.
|
