= Migration to Package Management = This document gives an overview of what changes with the migration to package management. It has sections for different groups of Haiku users. All applying sections should be read in order. == Changes for Users == * Almost all software lives in packages and is only virtually extracted. The virtually extracted package content is read-only. * Software (i.e. packages) can be installed via the command line package manager `pkgman` -- `pkgman search/install/uninstall/update ...` searches for, installs, uninstalls, and updates packages respectively. Packages can also be installed manually by moving (not copying) them to the respective "packages" subdirectory in "/boot/system", "/boot/common", or "/boot/home/config". * The directory layout has changed and many directories have become read-only. Cf. [wiki:PackageManagement/DirectoryStructure DirectoryStructure] for details. * The Deskbar menu works differently. It uses a new virtual directory Tracker/Deskbar feature to generate its content. Any package can contribute Deskbar menu entries by including respective symlinks in "data/deskbar/menu". The virtual directory merges the respective directories from all installation locations plus the user settings directory "/boot/home/config/settings/deskbar/menu". That means whenever a package is installed/removed its Desbar menu entries will be added/removed automatically. The user settings directory allows the user to add new entries manually. The whole behavior can be changed by overriding the default virtual directory. Before using the default virtual directory "/boot/system/data/deskbar/menu_entries" Deskbar first looks for "/boot/home/config/settings/deskbar/menu_entries". This can be a virtual directory as well, or a regular directory, or a symlink to either. E.g. making it a symlink to the "menu" directory will cause Deskbar to use only the contents of that directory, i.e. the menu contents is completely user-defined. * The MIME type management works a bit differently now as well. The database entries for the default MIME types are included in the system package and those for application MIME types are included in the package containing the respective applications. Neither of those can therefore be removed. By editing them in the FileTypes preferences application they can be overridden, though. ATM there are still a few known bugs and missing features -- e.g. application MIME types aren't automatically added/removed when installing/removing a package, and the MIME type removal functionality in FileTypes needs to be reworked. == Changes for Application Developers == * All development files (headers, libraries, the tool chain) have moved to "develop" in the respective installation location. Headers live in "develop/headers", development libraries in "develop/lib". Development libraries means besides static libraries also symlinks to shared libraries. The shared libraries themselves as well as all symlinks required to run a program using the library (at most one symlink per library -- the soname) live in "lib". * Commands, libraries, add-ons, and headers for the secondary architecture of a hybrid Haiku live in an "" subdirectory of their usual location. This doesn't hold for the system headers which exist only in the primary location. * `setgcc` is gone. The commands of the tool chain for the secondary architecture live in "/boot/common/bin/". Prepending that path to the `PATH` environment variable would make them shadow the respective primary architecture commands -- the effect would be similar to the one `setgcc` had, but only for the current shell session. The commands of the secondary tool chain are also available in the standard path with a name suffixed with "-" (e.g. "gcc-x86" for the gcc 4 executable on a gcc2/gcc4 hybrid). * Software can be packaged using the `package` tool. Cf. [wiki:PackageManagement/BuildingPackages BuildingPackages] for more information. == Changes for Haiku Developers == * Hybrid builds no longer require two separate generated directories. Instead the build is configured with both compilers and all output files are put in a single generated directory. * The notion of a packaging architecture has been introduced. It is mostly synonymous with the architecture, save for x86 where "x86_gcc2" refers to x86 gcc 2 and "x86" to x86 gcc 4. * Several `configure` script option have changed: * `--build-cross-tools` and `--build-cross-tools-gcc4` have been merged. The (packaging) architecture must always be specified. * `--build-cross-tools` and `--cross-tools-prefix` can be given multiple times to specify hybrid builds. Only for the first `--build-cross-tools` the path to the build tools must be given. * The new option `--target-arch` has been introduced for use on Haiku for builds with the native compiler. By default, if neither `--build-cross-tools` nor `--cross-tools-prefix` are specified the build is configured for a (hybrid) configuration matching the host system's (i.e. on a gcc2/gcc4 hybrid the build is configure for that configuration as well, on a pure gcc4 Haiku you'd get a gcc4 build). `--target-arch` overrides the default, allowing to specify the architecture to build for. The option can be given multiple times to specify a hybrid configuration. E.g. "--target-arch x86_gcc2 --target-arch x86" specifies a gcc2/gcc4 hybrid and can be used on a gcc2/gcc4 or gcc4/gcc2 Haiku. * The new option `--use-xattr-ref` can be used when extended attributes are available, but their size limit prevents use of `--use-xattr` (e.g. with ext4). The build system will use a slightly different version of the generic attribute emulation via separate files that involves tagging the attributed files with a unique ID, so there cannot be any mixups between attributes or different files when the inode ID of a file changes or files with attributes get deleted without removing their attribute files. * Configuring a gcc 2 build should now also work on a 64 bit system (without a 32 bit environment). Tested only on openSUSE 12.3 so far, but should also work on other Linux distributions and Unixes. The `--use-32bit` should therefore be superfluous. * build/jam has experienced some reorganization, particularly with respect to Haiku images and (optional) packages: * Most stuff that is built ends up in the "haiku.hpkg" and "haiku_devel.hpkg" packages (or the respective "haiku_.hpkg", "haiku__devel.hpkg" packages for the secondary architecture). The contents of the packages is defined in the respective files in the "packages" subdirectory. * The files defining the contents of the Haiku images live now in the "images" subdirectory. * The "repositories" subdirectory defines external repositories. Most relevant for a regular build is the HaikuPorts repository. For each architecture there is a file defining the contents of the repository. Changes in that file require a respective version of the repository to be built. Currently that has to be done manually on the haiku-files.org server. The process will be automated soon. * ReleaseBuildProfiles is now DefaultBuildProfiles. * The optional packages are mostly gone. There are only a few meta optional packages left. Adding regular packages to the image is done via the AddHaikuImagePackages rule. The parameters are package names (all lower case) without the version. * All build variables that depend on the architecture and aren't only relevant to the primary architecture have been renamed to have a "_" suffix (e.g. TARGET_GCC_, TARGET_DEFINES_, etc.). The variables are mostly only used by rule implementations, so this has not that much of an impact on Jamfiles. * There are new build variables HAIKU_PACKAGING_ARCHS and TARGET_PACKAGING_ARCH[S]. The plural versions are set to the list of all configured architectures, e.g. for a gcc2/gcc4 hybrid "x86_gcc2 x86". TARGET_PACKAGING_ARCH is set to the current architecture. Usually that means the primary architecture. In some cases (mostly for libraries) a target has to be built for all architectures. That is done in a loop which sets TARGET_PACKAGING_ARCH (and other variables) according to the architecture handled in that iteration. Cf. [https://github.com/haiku/HaikuPM/blob/package-management/src/kits/textencoding/Jamfile src/kits/textencoding/Jamfile] for a small example. * Build features (as defined in "build/jam/BuildFeatures") work differently now. Instead of build variables there are dedicated rules to deal with build features (FIsBuildFeatureEnabled, UseBuildFeatureHeaders, BuildFeatureAttribute). Cf. [https://github.com/haiku/HaikuPM/blob/package-management/src/add-ons/mail_daemon/inbound_protocols/pop3/Jamfile src/add-ons/mail_daemon/inbound_protocols/pop3/Jamfile] for an example. * The semantics of the "update" build profile action has changed somewhat, since due to the packages we now have two container levels, the image and the package. A `jam -q @alpha-raw update libbe.so` will first update libbe.so in the haiku.hpkg package and then update haiku.hpkg in the image. A `jam -q @alpha-raw update haiku.hpkg` will update "haiku.hpkg" in the image, but "haiku.hpkg" will not be rebuilt. If that is desired, it first has to be rebuilt explicitly -- via `jam -q haiku.hpkg`. Note that this might be problematic as well, since which optional build features are active depends on the specified build profile. * There's a new build profile action "update-packages". It updates all packages and then updates all packages in the image (including downloaded ones). It's a poor man's system update. Since it just copies the packages to the image, potentially replacing equally named packages, older packages with a different name will not be removed. Due to the system remembering which packages are active, it is recommended to empty the "/boot/{system,common}/packages" directories first (also removing the "administrative" subdirectory). == Changes for Porters == * The format of the recipe (formerly bep) files has changed. Many recipes have not been updated yet. haikuporter also has changed significantly. Cf. the [http://ports.haiku-files.org/wiki/HaikuPorterForPM haikuporter documentation] for more information.