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
9## Identifiers
10Each package is required to define at least these variables:
11
12    $(package)_version:
13    Version of the upstream library or program. If there is no version, a
14    placeholder such as 1.0 can be used.
15
16    $(package)_download_path:
17    Location of the upstream source, without the file-name. Usually http or
18    ftp.
19
20    $(package)_file_name:
21    The upstream source filename available at the download path.
22
23    $(package)_sha256_hash:
24    The sha256 hash of the upstream file
25
26These variables are optional:
27
28    $(package)_build_subdir:
29    cd to this dir before running configure/build/stage commands.
30
31    $(package)_download_file:
32    The file-name of the upstream source if it differs from how it should be
33    stored locally. This can be used to avoid storing file-names with strange
34    characters.
35
36    $(package)_dependencies:
37    Names of any other packages that this one depends on.
38
39    $(package)_patches:
40    Filenames of any patches needed to build the package
41
42    $(package)_extra_sources:
43    Any extra files that will be fetched via $(package)_fetch_cmds. These are
44    specified so that they can be fetched and verified via 'make download'.
45
46
47## Build Variables:
48After defining the main identifiers, build variables may be added or customized
49before running the build commands. They should be added to a function called
50$(package)_set_vars. For example:
51
52    define $(package)_set_vars
53    ...
54    endef
55
56Most variables can be prefixed with the host, architecture, or both, to make
57the modifications specific to that case. For example:
58
59    Universal:     $(package)_cc=gcc
60    Linux only:    $(package)_linux_cc=gcc
61    x86_64 only:       $(package)_x86_64_cc = gcc
62    x86_64 linux only: $(package)_x86_64_linux_cc = gcc
63
64These variables may be set to override or append their default values.
65
66    $(package)_cc
67    $(package)_cxx
68    $(package)_objc
69    $(package)_objcxx
70    $(package)_ar
71    $(package)_ranlib
72    $(package)_libtool
73    $(package)_nm
74    $(package)_cflags
75    $(package)_cxxflags
76    $(package)_ldflags
77    $(package)_cppflags
78    $(package)_config_env
79    $(package)_build_env
80    $(package)_stage_env
81    $(package)_build_opts
82    $(package)_config_opts
83
84The *_env variables are used to add environment variables to the respective
85commands.
86
87Many variables respect a debug/release suffix as well, in order to use them for
88only the appropriate build config. For example:
89
90    $(package)_cflags_release = -O3
91    $(package)_cflags_i686_debug = -g
92    $(package)_config_opts_release = --disable-debug
93
94These will be used in addition to the options that do not specify
95debug/release. All builds are considered to be release unless DEBUG=1 is set by
96the user. Other variables may be defined as needed.
97
98## Build commands:
99
100  For each build, a unique build dir and staging dir are created. For example,
101  `work/build/mylib/1.0-1adac830f6e` and `work/staging/mylib/1.0-1adac830f6e`.
102
103  The following build commands are available for each recipe:
104
105    $(package)_fetch_cmds:
106    Runs from: build dir
107    Fetch the source file. If undefined, it will be fetched and verified
108    against its hash.
109
110    $(package)_extract_cmds:
111    Runs from: build dir
112    Verify the source file against its hash and extract it. If undefined, the
113    source is assumed to be a tarball.
114
115    $(package)_preprocess_cmds:
116    Runs from: build dir/$(package)_build_subdir
117    Preprocess the source as necessary. If undefined, does nothing.
118
119    $(package)_config_cmds:
120    Runs from: build dir/$(package)_build_subdir
121    Configure the source. If undefined, does nothing.
122
123    $(package)_build_cmds:
124    Runs from: build dir/$(package)_build_subdir
125    Build the source. If undefined, does nothing.
126
127    $(package)_stage_cmds:
128    Runs from: build dir/$(package)_build_subdir
129    Stage the build results. If undefined, does nothing.
130
131  The following variables are available for each recipe:
132
133    $(1)_staging_dir: package's destination sysroot path
134    $(1)_staging_prefix_dir: prefix path inside of the package's staging dir
135    $(1)_extract_dir: path to the package's extracted sources
136    $(1)_build_dir: path where configure/build/stage commands will be run
137    $(1)_patch_dir: path where the package's patches (if any) are found
138
139Notes on build commands:
140
141For packages built with autotools, $($(package)_autoconf) can be used in the
142configure step to (usually) correctly configure automatically. Any
143$($(package)_config_opts) will be appended.
144
145Most autotools projects can be properly staged using:
146
147    $(MAKE) DESTDIR=$($(package)_staging_dir) install
148