1Each recipe consists of 3 main parts: defining identifiers, setting build
2variables, and defining build commands.
3
4The package "mylib" will be used here as an example
5
6General tips:
7- mylib_foo is written as $(package)_foo in order to make recipes more similar.
8- Secondary dependency packages relative to the bitcoin binaries/libraries (i.e.
9  those not in `ALLOWED_LIBRARIES` in `contrib/guix/symbol-check.py`) don't
10  need to be shared and should be built statically whenever possible. See
11  [below](#secondary-dependencies) for more details.
12
13## Identifiers
14If package does not define a `$(package)_local_dir` variable, it is required to
15define these variables:
16
17    $(package)_version:
18    Version of the upstream library or program. If there is no version, a
19    placeholder such as 1.0 can be used.
20
21    $(package)_download_path:
22    Location of the upstream source, without the file-name. Usually http, https
23    or ftp. Secure transmission options like https should be preferred if
24    available.
25
26    $(package)_file_name:
27    The upstream source filename available at the download path.
28
29    $(package)_sha256_hash:
30    The sha256 hash of the upstream file
31
32If a package does define a `$(package)_local_dir` variable, the above variables
33are not required and will be ignored.
34
35These variables are optional:
36
37    $(package)_build_subdir:
38    cd to this dir before running configure/build/stage commands.
39
40    $(package)_download_file:
41    The file-name of the upstream source if it differs from how it should be
42    stored locally. This can be used to avoid storing file-names with strange
43    characters.
44
45    $(package)_dependencies:
46    Names of any other packages that this one depends on.
47
48    $(package)_patches:
49    Filenames of any patches needed to build the package
50
51    $(package)_extra_sources:
52    Any extra files that will be fetched via $(package)_fetch_cmds. These are
53    specified so that they can be fetched and verified via 'make download'.
54
55## Local packages
56
57If a package defines a `$(package)_local_dir` variable, the specified directory
58will be treated as a download source, and a tarball of its contents will be
59saved to `sources/`. A hash of the tarball will also become part of the package
60build id, so if the directory contents change, the package and everything
61depending on it will be rebuilt. For efficiency, the tarball is cached once it
62has been created, but if the local directory is touched, it will be rebuilt.
63
64Local packages can be useful for using git submodules or subtrees to manage
65package sources, or for testing local changes that are not available to
66download from an external source.
67
68## Build Variables:
69After defining the main identifiers, build variables may be added or customized
70before running the build commands. They should be added to a function called
71$(package)_set_vars. For example:
72
73    define $(package)_set_vars
74    ...
75    endef
76
77Most variables can be prefixed with the host, architecture, or both, to make
78the modifications specific to that case. For example:
79
80    Universal:     $(package)_cc=gcc
81    Linux only:    $(package)_linux_cc=gcc
82    x86_64 only:       $(package)_x86_64_cc = gcc
83    x86_64 linux only: $(package)_x86_64_linux_cc = gcc
84
85These variables may be set to override or append their default values.
86
87    $(package)_cc
88    $(package)_cxx
89    $(package)_objc
90    $(package)_objcxx
91    $(package)_ar
92    $(package)_ranlib
93    $(package)_nm
94    $(package)_cflags
95    $(package)_cxxflags
96    $(package)_ldflags
97    $(package)_cppflags
98    $(package)_config_env
99    $(package)_build_env
100    $(package)_stage_env
101    $(package)_build_opts
102    $(package)_config_opts
103
104The *_env variables are used to add environment variables to the respective
105commands.
106
107Many variables respect a debug/release suffix as well, in order to use them for
108only the appropriate build config. For example:
109
110    $(package)_cflags_release = -O3
111    $(package)_cflags_i686_debug = -g
112    $(package)_config_opts_release = --disable-debug
113
114These will be used in addition to the options that do not specify
115debug/release. All builds are considered to be release unless DEBUG=1 is set by
116the user. Other variables may be defined as needed.
117
118## Build commands:
119
120  For each build, a unique build dir and staging dir are created. For example,
121  `work/build/mylib/1.0-1adac830f6e` and `work/staging/mylib/1.0-1adac830f6e`.
122
123  The following build commands are available for each recipe:
124
125    $(package)_fetch_cmds:
126    Runs from: build dir
127    Fetch the source file. If undefined, it will be fetched and verified
128    against its hash.
129
130    $(package)_extract_cmds:
131    Runs from: build dir
132    Verify the source file against its hash and extract it. If undefined, the
133    source is assumed to be a tarball.
134
135    $(package)_preprocess_cmds:
136    Runs from: build dir/$(package)_build_subdir
137    Preprocess the source as necessary. If undefined, does nothing.
138
139    $(package)_config_cmds:
140    Runs from: build dir/$(package)_build_subdir
141    Configure the source. If undefined, does nothing.
142
143    $(package)_build_cmds:
144    Runs from: build dir/$(package)_build_subdir
145    Build the source. If undefined, does nothing.
146
147    $(package)_stage_cmds:
148    Runs from: build dir/$(package)_build_subdir
149    Stage the build results. If undefined, does nothing.
150
151  The following variables are available for each recipe:
152
153    $(1)_staging_dir: package's destination sysroot path
154    $(1)_staging_prefix_dir: prefix path inside of the package's staging dir
155    $(1)_extract_dir: path to the package's extracted sources
156    $(1)_build_dir: path where configure/build/stage commands will be run
157    $(1)_patch_dir: path where the package's patches (if any) are found
158
159Notes on build commands:
160
161For packages built with autotools, $($(package)_autoconf) can be used in the
162configure step to (usually) correctly configure automatically. Any
163$($(package)_config_opts) will be appended.
164
165Most autotools projects can be properly staged using:
166
167    $(MAKE) DESTDIR=$($(package)_staging_dir) install
168
169## Build outputs:
170
171In general, the output of a depends package should not contain any libtool
172archives or `.pc` (`pkg-config`) files. Instead, the package should output
173`.cmake` (CMake) files where possible.
174
175From the [Gentoo Wiki entry](https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Handling_Libtool_Archives):
176
177>  Libtool pulls in all direct and indirect dependencies into the .la files it
178>  creates. This leads to massive overlinking, which is toxic to the Gentoo
179>  ecosystem, as it leads to a massive number of unnecessary rebuilds.
180
181Where possible, packages are built with Position Independent Code. Either using
182the Autotools `--with-pic` flag, or `CMAKE_POSITION_INDEPENDENT_CODE` with CMake.
183
184## Secondary dependencies:
185
186Secondary dependency packages relative to the bitcoin binaries/libraries (i.e.
187those not in `ALLOWED_LIBRARIES` in `contrib/guix/symbol-check.py`) don't
188need to be shared and should be built statically whenever possible. This
189improves general build reliability as illustrated by the following example:
190
191When linking an executable against a shared library `libprimary` that has its
192own shared dependency `libsecondary`, we may need to specify the path to
193`libsecondary` on the link command using the `-rpath/-rpath-link` options, it is
194not sufficient to just say `libprimary`.
195
196For us, it's much easier to just link a static `libsecondary` into a shared
197`libprimary`. Especially because in our case, we are linking against a dummy
198`libprimary` anyway that we'll throw away. We don't care if the end-user has a
199static or dynamic `libsecondary`, that's not our concern. With a static
200`libsecondary`, when we need to link `libprimary` into our executable, there's no
201dependency chain to worry about as `libprimary` has all the symbols.
202
203## Build targets:
204
205To build an individual package (useful for debugging), following build targets are available.
206
207    make ${package}
208    make ${package}_fetched
209    make ${package}_extracted
210    make ${package}_preprocessed
211    make ${package}_configured
212    make ${package}_built
213    make ${package}_staged
214    make ${package}_postprocessed
215    make ${package}_cached
216    make ${package}_cached_checksum
217