1=============================== 2Migration to Package Management 3=============================== 4This document gives an overview of what changes with the migration to package 5management. It has sections for different groups of Haiku users. All applying 6sections should be read in order. 7 8Changes for Users 9================= 10- Almost all software lives in packages and is only virtually extracted. The 11 virtually extracted package content is read-only. 12- Software (i.e. packages) can be installed via the command line package manager 13 ``pkgman`` -- ``pkgman search/install/uninstall/update ...`` searches for, 14 installs, uninstalls, and updates packages respectively. Packages can also be 15 installed manually by moving (not copying) them to the respective "packages" 16 subdirectory in "/boot/system" or "/boot/home/config". 17- The directory layout has changed and many directories have become read-only. 18 Cf. `DirectoryStructure`_ for details. 19 20 .. _DirectoryStructure: DirectoryStructure.rst 21 22- The Deskbar menu works differently. It uses a new virtual directory 23 Tracker/Deskbar feature to generate its content. Any package can contribute 24 Deskbar menu entries by including respective symlinks in "data/deskbar/menu". 25 The virtual directory merges the respective directories from all installation 26 locations plus the user settings directory 27 "/boot/home/config/settings/deskbar/menu". That means whenever a package is 28 installed/removed its Desbar menu entries will be added/removed automatically. 29 The user settings directory allows the user to add new entries manually. The 30 whole behavior can be changed by overriding the default virtual directory. 31 Before using the default virtual directory 32 "/boot/system/data/deskbar/menu_entries" Deskbar first looks for 33 "/boot/home/config/settings/deskbar/menu_entries". This can be a virtual 34 directory as well, or a regular directory, or a symlink to either. E.g. making 35 it a symlink to the "menu" directory will cause Deskbar to use only the 36 contents of that directory, i.e. the menu contents is completely user-defined. 37- The MIME type management works a bit differently now as well. The database 38 entries for the default MIME types are included in the system package and 39 those for application MIME types are included in the package containing the 40 respective applications. Neither of those can therefore be removed. By editing 41 them in the FileTypes preferences application they can be overridden, though. 42 ATM there are still a few known bugs and missing features -- e.g. application 43 MIME types aren't automatically added/removed when installing/removing a 44 package, and the MIME type removal functionality in FileTypes needs to be 45 reworked. 46- Haiku's stage 1 boot loader (the boot block in the BFS partition) has changed. 47 That means a Haiku partition made bootable from an old Haiku -- or more 48 generally: with a ``makebootable`` that predates package management -- will 49 not be able to boot a package management Haiku. You will have to run the new 50 ``makebootable`` to make it bootable again. The new ``makebootable`` may or 51 may not run on an old Haiku. The safest way is to do that from a running 52 package management Haiku (e.g. booted off a USB stick or CD). 53 54Changes for Application Developers 55================================== 56- All development files (headers, libraries, the tool chain) have moved to 57 "develop" in the respective installation location. Headers live in 58 "develop/headers", development libraries in "develop/lib". Development 59 libraries means besides static libraries also symlinks to shared libraries. 60 The shared libraries themselves as well as all symlinks required to run a 61 program using the library (at most one symlink per library -- the soname) live 62 in "lib". 63- Commands, libraries, add-ons, and headers for the secondary architecture of a 64 hybrid Haiku live in an "<arch>" subdirectory of their usual location. This 65 doesn't hold for the system headers which exist only in the primary location. 66- ``setgcc`` is gone. The commands of the tool chain for the secondary 67 architecture (by default) live in "/boot/system/bin/<arch>". Prepending that 68 path to the ``PATH`` environment variable would make them shadow the 69 respective primary architecture commands -- the effect would be similar to the 70 one ``setgcc`` had, but only for the current shell session. Executing the new 71 command ``setarch <arch>`` will start a new shell with a respectively modified 72 ``PATH``. The commands of the secondary tool chain are also available in the 73 standard path with a name suffixed with "-<arch>" (e.g. "gcc-x86" for the 74 gcc 4 executable on a gcc2/gcc4 hybrid). 75- Software can be packaged using the ``package`` tool. Cf. `BuildingPackages`_ 76 for more information. 77 78 .. _BuildingPackages: BuildingPackages.rst 79 80- The ``find_directory()`` API has been partially deprecated. While there are 81 still some use cases where it should be used, in many cases the new 82 ``find_path*()`` API, respectively the ``BPathFinder`` class should be used 83 instead (cf. the `API documentation`_). 84 85 .. _API documentation: https://www.haiku-os.org/docs/api/FindDirectory_8h.html 86 87Changes for Haiku Developers 88============================ 89- Hybrid builds no longer require two separate generated directories. Instead 90 the build is configured with both compilers and all output files are put in a 91 single generated directory. 92- The notion of a packaging architecture has been introduced. It is mostly 93 synonymous with the architecture, save for x86 where "x86_gcc2" refers to 94 x86 gcc 2 and "x86" to x86 gcc 4. 95- Several ``configure`` script option have changed: 96 97 - ``--build-cross-tools`` and ``--build-cross-tools-gcc4`` have been merged. 98 The (packaging) architecture must always be specified. 99 - ``--build-cross-tools`` and ``--cross-tools-prefix`` can be given multiple 100 times to specify hybrid builds. Only for the first ``--build-cross-tools`` 101 the path to the build tools must be given. 102 103 For example, for building the default configuration of Haiku from a file 104 system with proper xattr support, your configure options could look like 105 this:: 106 107 $ ./configure --build-cross-tools x86_gcc2 ../buildtools --build-cross-tools x86 --use-xattr 108 109- The new option ``--target-arch`` has been introduced for use on Haiku for 110 builds with the native compiler. By default, if neither 111 ``--build-cross-tools`` nor ``--cross-tools-prefix`` are specified the build 112 is configured for a (hybrid) configuration matching the host system's (i.e. 113 on a gcc2/gcc4 hybrid the build is configure for that configuration as well, 114 on a pure gcc4 Haiku you'd get a gcc4 build). ``--target-arch`` overrides 115 the default, allowing to specify the architecture to build for. The option 116 can be given multiple times to specify a hybrid configuration. E.g. 117 "--target-arch x86_gcc2 --target-arch x86" specifies a gcc2/gcc4 hybrid and 118 can be used on a gcc2/gcc4 or gcc4/gcc2 Haiku. 119- The new option ``--use-xattr-ref`` can be used when extended attributes are 120 available, but their size limit prevents use of ``--use-xattr`` (e.g. with 121 ext4). The build system will use a slightly different version of the generic 122 attribute emulation via separate files that involves tagging the attributed 123 files with a unique ID, so there cannot be any mixups between attributes or 124 different files when the inode ID of a file changes or files with attributes 125 get deleted without removing their attribute files. 126- Configuring a gcc 2 build should now also work on a 64 bit system (without a 127 32 bit environment). Tested only on openSUSE 12.3 so far, but should also work 128 on other Linux distributions and Unixes. The ``--use-32bit`` should therefore 129 be superfluous. 130- build/jam has experienced some reorganization, particularly with respect to 131 Haiku images and (optional) packages: 132 133 - Most stuff that is built ends up in the "haiku.hpkg" and "haiku_devel.hpkg" 134 packages (or the respective "haiku_<arch>.hpkg", "haiku_<arch>_devel.hpkg" 135 packages for the secondary architecture). The contents of the packages is 136 defined in the respective files in the "packages" subdirectory. 137 - The files defining the contents of the Haiku images live now in the "images" 138 subdirectory. 139 - The "repositories" subdirectory defines external repositories. Most relevant 140 for a regular build is the HaikuPorts repository. For each architecture 141 there is a file defining the contents of the repository. Changes in that 142 file require a respective version of the repository to be built. Currently 143 that has to be done manually on the haiku-files.org server. The process will 144 be automated soon. 145 - ReleaseBuildProfiles is now DefaultBuildProfiles. 146 147- The optional packages are mostly gone. There are only a few meta optional 148 packages left. Adding regular packages to the image is done via the 149 AddHaikuImagePackages rule. The parameters are package names (all lower case) 150 without the version. 151- All build variables that depend on the architecture and aren't only relevant 152 to the primary architecture have been renamed to have a "_<arch>" suffix (e.g. 153 TARGET_GCC_<arch>, TARGET_DEFINES_<arch>, etc.). The variables are mostly only 154 used by rule implementations, so this has not that much of an impact on 155 Jamfiles. 156- There are new build variables HAIKU_PACKAGING_ARCHS and 157 TARGET_PACKAGING_ARCH[S]. The plural versions are set to the list of all 158 configured architectures, e.g. for a gcc2/gcc4 hybrid "x86_gcc2 x86". 159 TARGET_PACKAGING_ARCH is set to the current architecture. Usually that means 160 the primary architecture. In some cases (mostly for libraries) a target has to 161 be built for all architectures. That is done in a loop which sets 162 TARGET_PACKAGING_ARCH (and other variables) according to the architecture 163 handled in that iteration. Cf. `src/kits/textencoding/Jamfile`_ for a small 164 example. 165 166 .. _src/kits/textencoding/Jamfile: 167 https://github.com/haiku/haiku/blob/master/src/kits/textencoding/Jamfile 168 169- Build features (as defined in "build/jam/BuildFeatures") work differently now. 170 Instead of build variables there are dedicated rules to deal with build 171 features (FIsBuildFeatureEnabled, UseBuildFeatureHeaders, 172 BuildFeatureAttribute). Cf. 173 `src/add-ons/mail_daemon/inbound_protocols/pop3/Jamfile`_ for an example. 174 175 .. _src/add-ons/mail_daemon/inbound_protocols/pop3/Jamfile: 176 https://github.com/haiku/haiku/blob/master/src/add-ons/mail_daemon/ 177 inbound_protocols/pop3/Jamfile 178- The semantics of the "update" build profile action has changed somewhat, since 179 due to the packages we now have two container levels, the image and the 180 package. A ``jam -q @alpha-raw update libbe.so`` will first update libbe.so in 181 the haiku.hpkg package and then update haiku.hpkg in the image. A 182 ``jam -q @alpha-raw update haiku.hpkg`` will update "haiku.hpkg" in the image, 183 but "haiku.hpkg" will not be rebuilt. If that is desired, it first has to be 184 rebuilt explicitly -- via ``jam -q haiku.hpkg``. Note that this might be 185 problematic as well, since which optional build features are active depends on 186 the specified build profile. 187- There's a new build profile action "update-packages". It updates all packages, 188 empties "/boot/system/packages" in the image, and copies the updated packages 189 there. It's a poor man's system update. Packages you have installed manually 190 will be removed. The old "update-all" build profile action still exits. It has 191 the effect of "update-packages" and additionally replaces all other files that 192 are usually copied to the image. 193 194Changes for Porters 195=================== 196- The format of the recipe (formerly bep) files has changed. Many recipes have 197 not been updated yet. haikuporter also has changed significantly. Cf. the 198 `haikuporter documentation`_ for more information. 199 200 .. _haikuporter documentation: 201 https://github.com/haikuports/haikuports/wiki/HaikuPorterForPM 202