1================= 2Building Packages 3================= 4 5This page provides information regarding the package building process. The first 6section documents building a package with the low level command ``package``. The 7second section refers to building packages with the ``haikuporter`` tool. 8 9Building a Package with the "package" Command 10============================================= 11The package file format is specified in detail in a `separate document`_. This 12section presents information from the perspective of how to build a package file 13with the ``package`` command. 14 15.. _separate document: FileFormat.rst 16 17An hpkg file is an archive file (just like tar or zip files) that additionally 18contains package meta information in a separate section of the file. When 19building an hpkg file via the ``package`` command the meta information must be 20provided via a ``.PackageInfo`` file. For convenience, the file itself is added 21to the archive as well and can be extracted later, but it will be ignored by 22packagefs. 23 24The ``.PackageInfo`` file must be located in the top directory that is archived. 25A ``package`` invocation usually looks like that:: 26 27 package create -C foo-4.5.26-1 foo-4.5.26-1-x86.hpkg 28 29or (packaging a gcc2 build from within the folder):: 30 31 cd foo-4.5.26-1 32 package create ../foo-4.5.26-1-x86_gcc2.hpkg 33 34The argument of the ``-C`` option specifies the directory whose contents to 35archive (by default the current directory), the remaining argument is the path 36of the package file to be built. 37 38The .PackageInfo 39---------------- 40The contents of the ``.PackageInfo`` adheres to a restricted driver settings 41syntax. It consists of name-value pairs, following this simple grammar:: 42 43 package_info ::= attribute* 44 attribute ::= name value_list 45 value_list ::= value | ( "{" value* "}" ) 46 value ::= value_item+ ( '\n' | ';' ) 47 48``name`` can be one of the attribute names defined below. ``value_item`` is 49either an unquoted string not containing any whitespace characters or a string 50enclosed in quotation marks (``"`` or ``'``) which can contain whitespace and 51also escaped characters (using ``\``). 52 53The supported attributes are: 54 55- ``name``: The name of the package, not including the package version. Must 56 only contain ``entity_name_char`` characters. 57 58 :: 59 60 entity_name_char ::= any character but '-', '/', '=', '!', '<', '>', or whitespace 61 62- ``version``: The version of the package. The string must have the ``version`` 63 format (see the `Version Strings`_ section). 64- ``architecture``: The system architecture the package has been built for. Can 65 be either of: 66 67 - ``any``: Any architecture (e.g. a documentation package). 68 - ``x86``: Haiku x86, built with gcc 4. 69 - ``x86_gcc2``: Haiku x86, built with gcc 2. 70 71- ``summary``: A short (one-line) description of the package. 72- ``description``: A longer description of the package. 73- ``vendor``: The name of the person/organization publishing this package. 74- ``packager``: The name and e-mail address of person that created this package 75 (e.g. "Peter Packman <peter.packman@example.com>"). 76- ``copyrights``: A list of copyrights applying to the software contained in 77 this package. 78- ``licenses``: A list of names of the licenses applying to the software 79 contained in this package. 80- ``urls``: A list of URLs referring to the packaged software's project home 81 page. The list elements can be regular URLs or email-like named URLs (e.g. 82 "Project Foo <http://foo.example.com>"). 83- ``source-urls``: A list of URLs referring to the packaged software's source 84 code or build instructions. Elements have the same format as those of 85 ``urls``. 86- ``flags``: A list of boolean flags applying to the package. Can contain any 87 of the following: 88 89 - ``approve_license``: This package's license requires approval (i.e. must be 90 shown to and acknowledged by user before installation). 91 - ``system_package``: This is a system package (i.e. lives under 92 "/boot/system"). 93 94- ``provides``: A list of entities provided by this package. The list elements 95 must have the following format:: 96 97 entity ::= entity_name [ "=" version_ref ] [ ( "compat" | "compatible" ) ">=" version_ref ] 98 entity_name ::= [ entity_type ":" ] entity_name_char+ 99 entity_type ::= "lib" | "cmd" | "app" | "add_on" 100 101 See the `Version Strings`_ section for the ``version_ref`` definition. 102 The first ``version_ref`` specifies the version of the provided entity. It 103 can be omitted e.g. for abstract resolvables like "web_browser". The 104 ``version_ref`` after the "compat"/"compatible" string specifies the oldest 105 version the resolvable is backwards compatible with. 106 The ``entity_type`` specifies the type of entity provided: a library ("lib"), 107 a command line program ("cmd"), an application ("app"), or an add-on 108 ("add-on"). 109- ``requires``: A list of entities required by this package. The list elements 110 must have the following format:: 111 112 required_entity ::= entity_name [ version_operator version_ref [ "base" ] ] 113 version_operator ::= "<" | "<=" | "==" | "!=" | ">=" | ">" 114 115 See the `Version Strings`_ section for the ``version_ref`` definition. If 116 "base" is specified, the specified entity is the base package for this 117 package. The package manager shall ensure that this package is installed in 118 the same installation location as its base package. 119- ``supplements``: A list of entities that are supplemented by this package 120 (i.e. this package will automatically be selected for installation if the 121 supplemented entities are already installed). The list elements must have the 122 ``required_entity`` format. 123- ``conflicts``: A list of entities that this package conflicts with (i.e. only 124 one of both can be installed at any time). The list elements must have the 125 ``required_entity`` format. 126- ``freshens``: A list of entities that are being freshened by this package 127 (i.e. this package will patch one or more files of the package(s) that provide 128 this entity). The list elements must have the ``required_entity`` format. 129- ``replaces``: A list of entities that are being replaced by this package (used 130 if the name of a package changes, or if a package has been split). The list 131 elements must have the ``entity_name`` format. 132- ``global-writable-files``: A list of global writable file infos. The list 133 elements must have the following format:: 134 135 global_writable_file_info ::= path [ "directory" ] [ "keep-old" | "manual" | "auto-merge" ] 136 137 ``path`` is the relative path of the writable file or directory, starting with 138 "settings/" or any other writable directory. If the "directory" keyword is 139 given, the path refers to a directory. If no other keyword is given after the 140 path respectively after the "directory" keyword, the file or directory is not 141 included in the package. It will be created by the software or by the user. 142 If a keyword is given, the file or directory (a default version) is included 143 in the package and it will be extracted on package activation. The keyword 144 specifies what shall happen when the package is updated and a previous default 145 version of the file or directory has been modified by the user: 146 147 - "keep-old": Indicates that the software can read old files and the 148 user-modified file or directory should be kept. 149 - "manual": Indicates that the software may not be able to read an older file 150 and the user may have to manually adjust it. 151 - "auto-merge": Indicates that the file format is simple text and a three-way 152 merge shall be attempted (not applicable for directories). 153 154- ``user-settings-files``: A list of user settings file infos. The list elements 155 must have the following format:: 156 157 user_settings_file_info ::= path [ "directory" | "template" template_path ] 158 159 ``path`` is the relative path of the settings file or directory, starting with 160 "settings/". It is not included in the package. However, if ``template_path`` 161 is specified, it is a path to a file included in the package that can serve as 162 a template for the settings file. It doesn't imply any automatic action on 163 package activation, though. If the "directory" keyword is given, the path 164 refers to a settings directory (typical when a program creates multiple 165 settings files). 166- ``users``: A list of specifications for Unix users the packaged software 167 requires. The list elements must have the following format:: 168 169 user: ::= name [ "real-name" real_name ] "home" home_path [ "shell" shell_path ] [ "groups" group+ ] 170 171 ``name`` is the name of the Unix user, ``real_name``, if specified, the real 172 name of the user, ``home_path`` the path to the user's home directory, 173 ``shell_path`` the path to the user's shell, and ``group+`` is a list of the 174 names of Unix groups the user is a member of (first one is their primary 175 group). If the respective components are not specified, ``name`` is also 176 used as the user's real name, "/bin/bash" is the path of the user's shell, 177 and the user will belong to the default user group. 178- ``groups``: A list of names of Unix groups the packaged software requires. 179- ``post-install-scripts``: A list of paths of files included in the package, 180 which shall be executed on package activation. Each path must start with 181 "boot/post-install/". All the files in that directory are also run on first 182 boot after installing or copying the OS to a new disk. As an odd bonus, 183 they're also run when you boot the installer disc, and the installer copies 184 some of the resulting settings data to the new install too. So try to 185 handle being run twice. 186- ``pre-uninstall-scripts``: A list of paths of files included in the package, 187 which shall be executed on package deactivation. For consistency, each path 188 should start with "boot/pre-uninstall/". 189 190Version Strings 191--------------- 192Versions strings are used in three contexts: For the package version, for 193resolvable versions (``provides``), and in dependency version expressions 194(``requires``, ``supplements``, ``conflicts``, ``freshens``). They are 195structurally identical, with the exception that the former requires a revision 196component (``version``), while the latter two don't (``version_ref``):: 197 198 version ::= major [ "." minor [ "." micro ] ] [ "~" pre_release ] "-" revision 199 version_ref ::= major [ "." minor [ "." micro ] ] [ "~" pre_release ] [ "-" revision ] 200 major ::= alphanum_underline+ 201 minor ::= alphanum_underline+ 202 micro ::= alphanum_underline_dot+ 203 pre_release ::= alphanum_underline_dot+ 204 revision ::= positive_non_zero_integer 205 206The meaning of the major, minor, and micro version parts is vendor specific. A 207typical, but not universal (!), convention is to increment the major version 208when breaking binary compatibility (i.e. version a.d.e is backwards compatible 209to version a.b.c for all b.c <= d.e), to increment the minor version when adding 210new features (in a binary compatible way), and to increment the micro version 211for bug fix releases. There are, however, projects that use different 212conventions which don't imply that e.g. version 1.4 is backwards compatible with 213version 1.2. Which convention is used is important for the packager to know, as 214it is required for a correct declaration of the compatibility versions for the 215provided resolvables. The compatibility version specifies the oldest version the 216provided resolvable is backwards compatible with, thus implying the version 217range requested by a dependent package the resolvable can satisfy. When 218following the aforementioned convention a resolvable of version 2.4.3 should 219have compatibility version 2 (or, semantically virtually identical, 2.0.0). 220Not following the convention 2.4 may be correct instead. If no compatibility 221version is specified, the resolvable can only satisfy dependency constraints 222with an exactly matching version. 223 224The pre-release part of the version string has special semantics for comparison. 225Unlike minor and micro its presence makes the version older. E.g. version 226R1.0~alpha1 is considered to be older than version R1.0. When both version 227strings have a pre-release part, that part is compared naturally after the micro 228part (R1.0.1~alpha1 > R1.0 > R1.0~beta1 > R1.0~alpha2). 229 230The revision part of the version string is assigned by the packager (not by the 231vendor). It allows to uniquely identify updated packages of the same vendor 232version of a software. 233 234Package File Names 235------------------ 236A package file name should have the following form:: 237 238 file_name ::= name "-" version "-" architecture ".hpkg" 239 240Example package file 241-------------------- 242:: 243 244 name example 245 version 42.17-12 246 architecture x86_gcc2 247 summary "This is an example package file" 248 description "Haiku has a very powerful package management system. Really, you should try it! 249 it even supports muliline strings in package descriptions" 250 packager "John Doe <test@example.com>" 251 vendor "Haiku Project" 252 licenses { 253 "MIT" 254 } 255 copyrights { 256 "Copyright (C) 1812-2013 by John Doe <test@example.com>" 257 } 258 provides { 259 example = 42.17-12 260 cmd:example = 3.1 261 } 262 requires { 263 haiku >= r1~alpha4_pm_hrev46213-1 264 lib:libpython2.6 >= 1.0 265 } 266 urls { 267 "http://example.com/" 268 } 269 global-writable-files { 270 "settings/example/configurationFile" keep-old 271 "settings/example/servers" directory keep-old 272 } 273 source-urls { 274 "Download <http://example.com/source.zip>" 275 } 276 277Building a Package with "haikuporter" 278===================================== 279``haikuporter`` is a high level tool for building packages. As input it reads a 280build recipe file for a certain version of a software (aka port) and produces 281one or more packages, as declared in the recipe. A recipe specifies package 282requirements similar to how it is done in a ``.PackageInfo`` file. When asked to 283build a port, ``haikuporter`` resolves the respective dependencies and 284recursively builds all not-yet-built ports required for the requested port. 285``haikuporter`` itself and a large library of recipe files are hosted at 286HaikuPorts_. A detailed `documentation for haikuporter`_ and the 287`recipe format`_ can also be found there. 288 289.. _HaikuPorts: https://github.com/haikuports/ 290 291.. _documentation for haikuporter: 292 https://github.com/haikuports/haikuports/wiki/HaikuPorterForPM 293 294.. _recipe format: 295 https://github.com/haikuports/haikuports/wiki/HaikuPorter-BuildRecipes 296