=================================Package Management Infrastructure=================================This pages gives an overview of what components belong to Haiku's packagemanagement infrastructure and how they work and interact.- **package** and **package_repo** are command line tools for building packageand package repository files. They are discussed in :ref:`building_packages`.- **packagefs** is the file system that virtually extracts activated packages.- The **package kit** is an API for package management related programming.- The **dependency solver** is a part of the package kit. It solves dependenciesbetween packages.- The **package management daemon** (short: package daemon) is a backgroundprocess that is activated whenever the user adds packages to or removes themfrom one of their activation locations. It verifies that all dependencies arefulfilled (prompting the user, if necessary) and performs whatever packagepre-activation/post-deactivation tasks are required. The daemon is alsocontacted by the package manager (after it has resolved dependencies anddownloaded all required packages) to do the package de-/activation.- The **package manager** provides the user interface for software installation,update, and removal. There are actually two programs, ``pkgman``, a commandline tool, and, ``HaikuDepot``, a GUI application... image:: package-management-infrastructure.png:align: centerSoftware Installation Locations===============================In Haiku there are two main locations where software is installed."/boot/system" and "/boot/home/config". "/boot/system" is where system-widesoftware (i.e. software for all users), including the base system, is installed,while "/boot/home/config" is only for the user's software. The discriminationbetween those two doesn't make that much sense yet, but when Haiku supportsmulti-user it will (obviously each user will need their own home directory then,e.g. "/boot/home/<user>").At both main installation locations a packagefs instance is mounted. Eachinstance presents a virtually extracted union of the contents of all packages inthe subdirectory "packages" of that location. E.g. if one would extract thecontents of all package files in "/boot/system/packages" to an actual directory,that would match exactly what is presented by packagefs in "/boot/system". Witha few exceptions -- packagefs provides several additional directories.There are so-called shine-through directories which live on the underlying BFSvolume. Normally a file system mounted at a directory would completely hideanything that is in that directory. These shine-through directories are handledspecially, though; packagefs shows them just like they are on the BFS volume.One of those directories is "packages". This is necessary since otherwise itwouldn't be possible to add, remove, or update any packages. Furthershine-through directories are "settings", "cache", "var", and "non-packaged".The latter is a place where software can be installed the "traditional",i.e. unpackaged, way.Software Installation=====================Manual Installation-------------------At the lowest level software can be installed by simply dropping a respectivepackage file in a "packages" subdirectory of one of "/boot/system" or"/boot/home/config". The package daemon, a background process that sleeps mostof the time, monitors the directory and, when happy with the newly addedpackage, it asks packagefs to presents its contents on the fly in the directorystructure. The package is said to be activated. Removing a package has theopposite effect.Things are a bit more complicated due to the fact that packages usually havedependencies. E.g. when adding a package that has an unsatisfied dependency(e.g. needs a certain library that is not installed) it is not a good idea toactivate the package nonetheless. The package contents (programs, libraries,...)might not work correctly, and, e.g. when shadowing other installed software,might even break things that worked before.That's why the package daemon doesn't just activate any well-formed packages.Instead it examines the new situation and checks whether all dependencies arefulfilled and whether there are any conflicts. If they aren't any problems, ittells packagefs to activate/deactivate the packages as requested. In case thereare issues with the dependencies, according to how it has been configured viasettings, the daemon prompts the user immediately, checks remote repositoriesfor solutions to the problem and presents the user with the possible options, orit even performs all necessary actions without bothering the user, if possible.In the end, if the problems could be solved (e.g. by downloading additionalpackages), the respective packages will be de-/activated, or, otherwise, nothingwill be changed.To avoid always having to check all dependencies when booting, the packagedaemon writes the last consistent state of package activations to the file"packages/administrative/activated-packages". When being mounted packagefs,reads that file and only activates the packages specified by it. If the file ismissing or packages it refers to cannot be found or loaded, packagefs falls backto activating all packages in the "packages" directory. The package daemon, oncestarted, checks the state.Installation via Package Manager--------------------------------While manual software installation is possible, the more comfortable way is touse the package manager. The package manager has a configurable list of remotesoftware repositories. It knows what software is available in those repositoriesand what is installed locally. After the user has selected software packages tobe installed/deinstalled, package dependencies are resolved, and packages aredownloaded and moved to their installation location.The package manager prepares a transaction directory, a subdirectory in the"packages/administrative" directory, which contains the new packages. It thencontacts the package management daemon (via the package kit) to perform thepackage activation changes. The daemon moves the new packages to the "packages"directory, moves obsolete packages to an old state directory (also asubdirectory in the "packages/administrative" directory, with the currentdate and time encoded in its name) and asks packagefs to activate/deactivate therespective packages. The old state directories allow recovery of old states.That is particularly interesting for the system installation location. As assafe mode/recovery option, the boot loader offers the user to select an oldinstallation state which can then be booted into, instead of the latest state.Application Bundles-------------------Haiku also supports a concept that is commonly referred to as applicationbundles. An application bundle is a fully self-contained package that doesn'tneed to be installed anywhere. The implementation details have not yet beendecided on. The basic idea is to either mount a dedicated packagefs with thecontent of such a package or have a special location where one of the threealready mounted packagefs instances (likely the "/boot/home/config" one) showsthat content. With a bit of Tracker (or even libbe) integration that will allowthe mounted directory to be opened or the application to be started when such apackage file has been double-clicked.Installation Location Order and Consistency-------------------------------------------Having two separate installation locations for software requires someconsiderations regarding their consistency and interactions. There's awell-defined order of the installation locations: "/boot/home/config","/boot/system". This has already been the order in which on BeOS commands,libraries, and add-ons where searched (according to the environmental variables``PATH``, ``LIBRARY_PATH``, and ``ADDON_PATH``). That e.g. allows a user toinstall a new/different version of a program in "/boot/home/config" and have itoverride the version in "/boot/system".This order also needs to be the order in which package dependencies aredirected. While it shall be possible to have a library in "/boot/home/config"override one in "/boot/system" and have programs installed in the latterlocation use the overriding library, packages in an installation location mustnot have dependencies that can only be resolved to packages installed in alocation that is prior according to the order. E.g. a program installed in"/boot/system" must not depend on a library that is only installed in"/boot/home/config". When going multi-user that would mean the program wouldwork for one user, but not for another one who hasn't installed the library.Consequently "/boot/system" is fully self-contained. All dependencies must beresolved within it. A safe-mode boot should be possible with only the"/boot/system" packagefs being mounted. As a consequence these constraints haveto be respected when software is installed or uninstalled.Another challenge that comes with having two installation locations is that somepackages have compiled-in absolute paths to their own files (e.g. data files) orto their dependencies. The former could be solved by building two differentversions of a package, but that wouldn't work with the latter and would betedious anyway. The solution are dynamically generated symbolic links in a fixedlocation, "/boot/system/package-links" (symlinked to "/packages"), that for eachinstalled package and its dependencies refer to the respective installationlocation.For each installed package a subdirectory named like the package (package nameplus version) will be generated automatically. That subdirectory contains asymlink ".self" which refers to the installation location of the package itselfas well as a symlink for each of its dependencies pointing to their installationlocations. Furthermore there's a symlink ".settings" which points to theinstallation location's directory for global settings. E.g. for an OpenSSHpackage installed in "/boot/home/config" and OpenSSL installed in "/boot/system"the directory could look like this::/boot/system/package-links/openssh-5.8p2-1/.self -> ../../../home/config.settings -> ../../../home/config/settings/globalhaiku -> ../..lib:libssl -> ../..Installing a different, compatible version of OpenSSL in "/boot/home/config"would automatically change the respective dependency symlink. Once supportingmulti-user fully, the symlinks targets would also depend on the user ID of theprocess that checks them, so software installed only for the user is handledcorrectly.While it depends on the location the package has been installed in where thepaths refer to, the absolute paths of the package links themselves remainstable. So they can be compiled in, when a package is built, and will workregardless of where the package is installed.Another problem the package links can solve are incompatible versions of thesame package being installed in different locations. E.g. when a program andanother program it depends on are installed in "/boot/system", installing anincompatible version of the latter in "/boot/home/config" will not break theformer, since the dependency link will continue to point to the compatibleversion. With a bit of help from the runtime loader the same would work forlibraries. In practice that's less of a problem, though, since libraries usuallyhave a naming scheme and matching shared object names that already preventmismatches.Software Repositories=====================A software repository is a collection of packages, usually accessible via theinternet. Haiku's package management solution allows to refer to any number ofsoftware repositories from which packages can be downloaded and installed. Thestructure of the respository is very simple. It's just a set of files which canbe downloaded via a common protocol (HTTP or FTP). One file is the repositoryindex file in :ref:`hpkr_file_format`. It lists all packages that are available in therepository together with their descriptions and dependency information. It isdownloaded and cached, allowing user interfaces to show the information and thedependency solver to do the computation locally. The other files are theindividual package files.Standard Repositories---------------------There are two standard repositories for Haiku:- the Haiku repository, which only contains the small set of packages that isbuilt by Haiku's build system (haiku.hpkg, haiku_devel.hpkg, etc.) and- the HaikuPorts repository, which contains the packages maintained byHaikuPorts.For the different builds and releases there are different instances of those tworepositories:- There are snapshot repository instances for any repository version that wasever available (to save space old versions may be removed/thinned out). Thoserepositories will never be updated. Their main purpose is to be able toretrospectively get a certain Haiku version for testing and comparisons.- For each official major release there will be an instance of the tworepositories. For small updates the repositories will simply be updated. Anofficial Haiku release is pre-configured with the corresponding repositories,so that the user can conveniently keep their Haiku up-to-date. The update tothe next major release has to be requested explicitly.- Similar to the nightly images there are repository instances that arecontinuously updated to the latest head of development. Those are suitablemainly for testers and developers.- For each state of the HaikuPorts repository a Haiku development revisionrefers to a snapshot version of the repository is created. This allows tocheck out and build older Haiku revisions with their corresponding HaikuPortspackages.The repositories are maintained via files in the Haiku git repository. For eacharchitecture and each repository the Haiku git repository contains a filelisting the packages for that repository. For the HaikuPorts repositories thepackages are listed with the respective version. For the Haiku repositories theversion is implied.Whenever a developer wants to update or add a HaikuPorts package, the newpackage file has to be uploaded to their git.haiku-os.org account and thepackage list file for the repository has to be adjusted accordingly.``jam upload-packages <packages-list>`` can be used in order to upload thepackage(s) or the packages could just be ``scp``'ed into the 'hpkg-upload'folder in the developer home directory on git.haiku-os.org. When that is done,the change can be pushed to git.haiku-os.org, where a push hook will analyze thechange, move the new package file(s) from the developer's account to therepository directory, and build a new repository snapshot. If a package file ismissing or broken, the push will be rejected with a message notifying thedeveloper about the problem.The creation and update of repositories for official releases has to betriggered explicitly on the server. In either case the Haiku repository is builtby the build service.The Package Kit===============The package kit provides an API for all package management related tasks,including:- Reading and writing HPKG and HPKR files.- Adding, removing, and querying software repositories.- Solving package dependencies.- Adding, removing, and updating packages.Localization============Package files and repository index files contain text strings -- e.g. thepackage short and long description -- that are presented to the user. Thereforetranslations for these strings must be available. Since it is impractical toinclude the translations in the package and repository index files, they must beprovided in separate files. How exactly has not been decided on yet.