1================ 2Packaging Policy 3================ 4This document defines the policy for creating packages. 5 6Multiple Packages per Software 7============================== 8Installation files of a software shall be put into separated packages according 9to their purpose. For a software "foo": 10 11- Package "foo": Contains all runtime files, i.e. everything needed to "run" the 12 software. This may include executables (e.g. executable "bin/foo"), shared 13 libraries (e.g. "lib/libfoo.so"), data files 14 (e.g. "data/foo/foo-runtime-data"). 15- Package "foo_devel": Contains only the files needed for development. This 16 includes header files and static libraries. Shared libraries are not to be 17 included. Instead the package must declare package "foo" with the matching 18 version as a requirement. 19- Package "foo_doc": Contains the documentation for using "foo". 20- Package "foo_devel_doc": Contains the documentation for "foo" development, 21 like API documentation etc. 22- Package "foo_debuginfo": Contains the debug information for the package "foo". 23 24If multiple packages are defined, they must not contain any common files. 25 26If a software contains client and server software that can be used independently 27from each other, two separate sets of packages shall be created. 28 29Provides Declaration 30==================== 31A package "foo" must declare the following provided resolvables: 32 33- "foo=<version>" with <version> naming the exact version of the package. 34- "cmd:<name>=<version>" for each executable <name> with version <version> 35 installed in "bin/". This includes a declaration for "cmd:foo", if there is an 36 executable named like the package. 37- "lib:<name>=<version>" for each shared library <name> (not including a suffix, 38 e.g. "libfoo") with version <version> installed in "lib/". 39- "devel:<name>=<version>" for each library <name> (not including a suffix, 40 e.g. "libfoo") with version <version> for which development files (library 41 symlinks in "develop/lib" and header files in "develop/headers") are included. 42 43Any instance of '-' in <name> shall be replaced by '_'. If the backward 44compatibility of a resolvable is known, a "compat >= <compatibleVersion>" shall 45be added accordingly. 46 47Documentation 48============= 49If a package "foo" provides documentation (which it should, of course), in many 50cases that can be provided in different formats: 51 52- Any kind of user documentation belongs in a subdirectory of "documentation" 53 54 - Man pages is the preferred format for terminal and should be installed into 55 the corresponding folders in the subdirectory "man". 56 - Info files are provided by many packages. If at all desirable, they should 57 be installed into the subdirectory "info". One problem with info files is 58 that all packages currently contain a file named "documentation/info/dir", 59 which supposedly is the list of all available info files, but since each 60 package provides an instance of this file containing only its own info 61 files, an arbitrary dir file is made visible via packagefs. The file should 62 therefore not be include in a package. 63 - Other documentation for a package foo -- HTML, a simple ReadMe, sample 64 documents, PDFs, etc. -- goes into subdirectory "packages/foo". If it is 65 likely that multiple versions of a package may be installed, then a version 66 string (as appropriate just major, major and minor, or even full (but no 67 revision)) should be appended, e.g. "package/foo-2" or "package/foo-2.13". 68 69- For a package foo_devel developer documentation, except man and info pages, 70 should go into "develop/documentation/foo". A version string may be appended 71 to the directory name as well. When it is unclear what is developer 72 documentation or it isn't really possible to separate it from user 73 documentation "documentation/foo" should be used. 74 75Data Files 76========== 77Data files for a package foo shall generally be placed in a directory 78"data/foo". If it is likely that multiple versions of a package may be 79installed, then a version string shall be appended. Data (but not 80settings/configuration) files generated at run-time shall be placed in 81"cache/foo" or "var/foo", depending on the kind of data the files contain. For 82data files, both read-only or generated, that are shared between different 83packages/software a differently named subdirectory may be used as appropriate 84(e.g. font files are placed in "data/fonts"). 85 86Writable and Settings Files and Directories 87=========================================== 88All global writable files and directories as well as user settings files and 89directories that the package includes or the packaged software creates or 90requires the user to create shall be declared by the package (via 91GLOBAL_WRITABLE_FILES respectively USER_SETTINGS_FILES in the build recipe) in 92the following way: 93 94- A user specific settings file shall never be installed on package activation. 95 Usually user specific settings files are completely optional. In the rare case 96 that a software requires a user specific settings, the user will have to 97 create it manually. In either case, if the package includes a template user 98 settings file, that should be declared:: 99 100 USER_SETTINGS_FILES="settings/foo template data/foo/user-settings-template" 101 102 If no template file is included, the settings file shall still be declared:: 103 104 USER_SETTINGS_FILES="settings/foo" 105 106- Since many ported software requires a global settings file or other writable 107 files, a default version of such a file can be provided and is automatically 108 installed on package activation. In that case the package must also declare 109 what shall be done with a user-modified file when the package is updated. 110 E.g.:: 111 112 GLOBAL_WRITABLE_FILES="settings/foo keep-old" 113 114 "keep-old" indicates that the software can read old files and the 115 user-modified file should be kept. "manual" indicates that the software may 116 not be able to read an older file and the user may have to manually adjust it. 117 "auto-merge" indicates that the file format is simple text and a three-way 118 merge shall be attempted. If a default settings file is not included in the 119 package, the settings file shall still be declared, just without the 120 additional keyword. 121 122In both cases, user settings files and global writable files, the "directory" 123keyword can be used to indicate that the given path actually refers to a 124directory. 125 126Post-Installation Scripts 127========================= 128A package may include one or more post-installation scripts. The scripts are 129executed whenever the package is activated (for the first time, but also after 130package updates and first boot of a newly installed OS). They shall be placed 131in "boot/post-install" and declared explicitly by the package (via 132POST_INSTALL_SCRIPTS in the build recipe). A post-install script should be 133considered the last resort. It should only be used, if there's no reasonable 134alternative. A typical use would be to create a desktop icon that the user 135can move around or delete. 136 137Pre-Uninstallation Scripts 138========================== 139These undo the effects of a post-installation script and usually are put 140into "boot/pre-uninstall". A typical use is to remove desktop icons. 141