depends/packages.md

   1 Each recipe consists of 3 main parts: defining identifiers, setting build
   2 variables, and defining build commands.
   3
   4 The package "mylib" will be used here as an example
   5
   6 General tips:
   7 - mylib_foo is written as $(package)_foo in order to make recipes more similar.
   8
   9 ## Identifiers
  10 Each 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
  26 These 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:
  48 After defining the main identifiers, build variables may be added or customized
  49 before 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
  56 Most variables can be prefixed with the host, architecture, or both, to make
  57 the 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
  64 These 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
  84 The *_env variables are used to add environment variables to the respective
  85 commands.
  86
  87 Many variables respect a debug/release suffix as well, in order to use them for
  88 only 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
  94 These will be used in addition to the options that do not specify
  95 debug/release. All builds are considered to be release unless DEBUG=1 is set by
  96 the 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
 139 Notes on build commands:
 140
 141 For packages built with autotools, $($(package)_autoconf) can be used in the
 142 configure step to (usually) correctly configure automatically. Any
 143 $($(package)_config_opts) will be appended.
 144
 145 Most autotools projects can be properly staged using:
 146
 147     $(MAKE) DESTDIR=$($(package)_staging_dir) install