i2p/haiku-beta6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs/develop/packages: convert wiki to rst

Browse Source 
Cleaner syntax compared to MediaWiki, more features than Markdown, while
still looks good on plain text.
This commit is contained in:
Leorize
2018-03-03 20:22:46 +00:00
committed by waddlesplash
parent 6285deba8e
commit 03d384bbfb
22 changed files with 2860 additions and 1832 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/develop/packages/Bootstrapping.rst
+144
View File
@@ -0,0 +1,144 @@
===================
Bootstrapping Haiku
===================
Even a very basic Haiku requires a set of third-party packages (ICU, zlib,...),
a Haiku sufficiently complete to build software even more
(binutils, gcc, make,...). So whenever something fundamental in Haiku
(the architecture ABI, the ABI of libroot) changes in a binary incompatible way,
or when Haiku is ported to a new architecture, it is necessary to bootstrap
Haiku and a basic set of required third-party packages. This document describes
how this process works.
Prerequisites
=============
- So far the bootstrap build has only been tested on Linux. It will probably
also work on FreeBSD and other Unixes. Haiku is not yet supported as a build
platform.
- A required prerequisite for the bootstrap build is a checkout of the
haikuporter, the haikuports, and the haikuports.cross repositories from the
`Github HaikuPorts site`_.
.. _Github HaikuPorts site: https://github.com/haikuports/
- Additional build tools are required for the build platform:
- autoconf
- automake
- cmake (For compiling python_bootstrap)
- ncurses_development (For compiling texinfo_bootstrap)
- All the usual prerequisites for building Haiku.
Configuring and Building
========================
1. Configure the Haiku build with all usual parameters, but add the
``--bootstrap`` option with its three parameters, the paths to the checked
out haikuporter *script* (eg. ``../haikuporter/haikuporter``),
haikuports.cross, and haikuports repositories folders::
.../configure ... --bootstrap path/to/haikuporter path/to/haikuports.cross path/to/haikuports
It is important that you build outside the tree, as otherwise the build will
fail!
#. Build a bootstrap Haiku image::
jam -q @bootstrap-raw
#. Boot the bootstrap Haiku (e.g. in a virtual machine), edit the file
"/boot/home/haikuports/haikuports.config" -- entering your email address in
the "PACKAGER" field -- and finally open a Terminal and build the third-party
packages::
cd haikuports
haikuporter --do-bootstrap
In the "packages" subdirectory the built packages are collected. This is the
initial set of packages for the HaikuPorts packages repository, plus the source
packages the Haiku build system put in your generated directory under
"objects/haiku/<arch>/packaging/repositories/HaikuPorts-sources-build/packages"
(ignore the "rigged" source packages). With these packages a HaikuPorts package
repository can be built and in turn a regular Haiku can be built using it.
Further packages can then be built on the regular Haiku.
Further hints:
- Of course, as usual, "-j<number>" can be passed to the jam building the
bootstrap Haiku. Building the bootstrap third-party packages, which is part of
this process, will take quite some time anyway. Since those packages are built
sequentially, the jam variable "HAIKU_PORTER_CONCURRENT_JOBS" can be defined
to the number of jobs that shall be used to build a package.
- Instead of "bootstrap-raw" the build profile "bootstrap-vmware" can be used as
well. You can also define your own build profile, e.g. for building to a
partition. As long as its name starts with "bootstrap-" that will result in a
bootstrap Haiku.
- ``haikuporter`` also supports the "-j<number>" option to specify the number of
jobs to use. Even on real hardware this step will nevertheless take a long
time.
- The jam variable HAIKU_PORTER_EXTRA_OPTIONS can be defined to any options that
should be passed to ``haikuporter`` (``--debug`` is handy for showing python
strack traces, for instance).
How it works
============
Building the bootstrap Haiku image is in principle quite similar to building a
regular Haiku image, save for the following differences:
- Some parts of a regular Haiku that aren't needed for building packages are
omitted (e.g. the Demos, MediaPlayer, the OpenGL API,...).
- Certain third-party packages that aren't needed for building packages are
omitted as well.
- The third-party packages are not downloaded from some package repository.
Instead for each package a bootstrap version is built from the sources using
``haikuporter`` and the respective build recipe from haikuports.cross.
- ``haikuporter`` itself and ready-to-build ("rigged") source packages for all
needed final third-party packages are copied to the image.
Obviously the last two points are the juicy parts. Building a bootstrap
third-party package -- unless it is a pure data package -- requires certain
parts of Haiku; usually the headers, libroot and other libraries, and the glue
code. For some Haiku libraries we do already need certain third-party packages.
So there's a bit of ping pong going on:
- Initially the build system builds a package
"haiku_cross_devel_sysroot_stage1_<arch>.hpkg". It contains the essentials for
cross-compiling bootstrap third-party packages, but nothing that itself
depends on a third-party package.
- Once all third-party packages required for it have been built, a more complete
"haiku_cross_devel_sysroot_<arch>.hpkg" is built. It is used to cross-compile
the remaining third-party packages.
The rigged source packages (and regular source packages) are built via
``haikuporter`` from the regular haikuports repository checkout. haikuports
contains build recipes for a lot of software. Which source packages should be
built is determined by the build system by checking what packages are needed for
the target build profile used by the bootstrap process. This defaults to
"minimum-raw", but it can be changed by setting the jam variable
"HAIKU_BOOTSTRAP_SOURCES_PROFILE"
(i.e. ``jam -sHAIKU_BOOTSTRAP_SOURCES_PROFILE=@release-raw -q @bootstrap-raw``
will include source packages for all packages needed by release image).
Haiku Architecture Ports
========================
When preparing a new Haiku architecture port for the bootstrap build the
following things need to be considered:
- There need to be repository definitions
"build/jam/repositories/HaikuPorts/<arch>" and
"build/jam/repositories/HaikuPortsCross/<arch>". The former lists the packages
available for a regular Haiku, i.e. it must include at least the packages
needed for a basic Haiku image that can build third-party packages. The latter
lists the available bootstrap third-party packages.
- There needs to be "src/data/package_infos/<arch>/haiku", a package info for
the Haiku system package (currently also used for the bootstrap package).
- In the haikuports.cross repository all build recipes need to support the
architecture (the architecture must be listed in the "ARCHITECTURES"
variable). Some software may need to be patched for cross-building to work for
the architecture.
- In the haikuports repository all build recipes for required software need to
support the architecture.
If the Haiku architecture port doesn't support a working userland yet, the
process obviously cannot go further than building the bootstrap Haiku image.
docs/develop/packages/Bootstrapping.wiki
-68
View File
@@ -1,68 +0,0 @@
== Bootstrapping Haiku ==
Even a very basic Haiku requires a set of third-party packages (ICU, zlib,...), a Haiku sufficiently complete to build software even more (binutils, gcc, make,...). So whenever something fundamental in Haiku (the architecture ABI, the ABI of libroot) changes in a binary incompatible way, or when Haiku is ported to a new architecture, it is necessary to bootstrap Haiku and a basic set of required third-party packages. This document describes how this process works.
=== Prerequisites ===
*So far the bootstrap build has only been tested on Linux. It will probably also work on FreeBSD and other Unixes. Haiku is not yet supported as a build platform.
*A required prerequisite for the bootstrap build is a checkout of the haikuporter, the haikuports, and the haikuports.cross repositories from the [https://github.com/haikuports/ Github HaikuPorts site].
*Additional build tools are required for the build platform:
- autoconf
- automake
- cmake (For compiling python_bootstrap)
- ncurses_development (For compiling texinfo_bootstrap)
*All the usual prerequisites for building Haiku.
=== Configuring and Building ===
#Configure the Haiku build with all usual parameters, but add the <tt>--bootstrap</tt> option with its three parameters, the paths to the checked out haikuporter ''script'' (eg. <tt>../haikuporter/haikuporter</tt>), haikuports.cross, and haikuports repositories folders:
<pre>
.../configure ... --bootstrap path/to/haikuporter path/to/haikuports.cross path/to/haikuports
</pre>
It is important that you build outside the tree, as otherwise the build will fail!
#Build a bootstrap Haiku image:
<pre>
jam -q @bootstrap-raw
</pre>
#Boot the bootstrap Haiku (e.g. in a virtual machine), edit the file "/boot/home/haikuports/haikuports.config" -- entering your email address in the "PACKAGER" field -- and finally open a Terminal and build the third-party packages:
<pre>
cd haikuports
haikuporter --do-bootstrap
</pre>
In the "packages" subdirectory the built packages are collected. This is the initial set of packages for the HaikuPorts packages repository, plus the source packages the Haiku build system put in your generated directory under "objects/haiku/<arch>/packaging/repositories/HaikuPorts-sources-build/packages" (ignore the "rigged" source packages). With these packages a HaikuPorts package repository can be built and in turn a regular Haiku can be built using it. Further packages can then be built on the regular Haiku.
Further hints:
*Of course, as usual, "-j<number>" can be passed to the jam building the bootstrap Haiku. Building the bootstrap third-party packages, which is part of this process, will take quite some time anyway. Since those packages are built sequentially, the jam variable "HAIKU_PORTER_CONCURRENT_JOBS" can be defined to the number of jobs that shall be used to build a package.
*Instead of "bootstrap-raw" the build profile "bootstrap-vmware" can be used as well. You can also define your own build profile, e.g. for building to a partition. As long as its name starts with "bootstrap-" that will result in a bootstrap Haiku.
*<tt>haikuporter</tt> also supports the "-j<number>" option to specify the number of jobs to use. Even on real hardware this step will nevertheless take a long time.
*The jam variable HAIKU_PORTER_EXTRA_OPTIONS can be defined to any options that should be passed to <tt>haikuporter</tt> (<tt>--debug</tt> is handy for showing python strack traces, for instance).
=== How it works ===
Building the bootstrap Haiku image is in principle quite similar to building a regular Haiku image, save for the following differences:
*Some parts of a regular Haiku that aren't needed for building packages are omitted (e.g. the Demos, MediaPlayer, the OpenGL API,...).
*Certain third-party packages that aren't needed for building packages are omitted as well.
*The third-party packages are not downloaded from some package repository. Instead for each package a bootstrap version is built from the sources using <tt>haikuporter</tt> and the respective build recipe from haikuports.cross.
*<tt>haikuporter</tt> itself and ready-to-build ("rigged") source packages for all needed final third-party packages are copied to the image.
Obviously the last two points are the juicy parts. Building a bootstrap third-party package -- unless it is a pure data package -- requires certain parts of Haiku; usually the headers, libroot and other libraries, and the glue code. For some Haiku libraries we do already need certain third-party packages. So there's a bit of ping pong going on:
*Initially the build system builds a package "haiku_cross_devel_sysroot_stage1_<arch>.hpkg". It contains the essentials for cross-compiling bootstrap third-party packages, but nothing that itself depends on a third-party package.
*Once all third-party packages required for it have been built, a more complete "haiku_cross_devel_sysroot_<arch>.hpkg" is built. It is used to cross-compile the remaining third-party packages.
The rigged source packages (and regular source packages) are built via <tt>haikuporter</tt> from the regular haikuports repository checkout. haikuports contains build recipes for a lot of software. Which source packages should be built is determined by the build system by checking what packages are needed for the target build profile used by the bootstrap process. This defaults to "minimum-raw", but it can be changed by setting the jam variable "HAIKU_BOOTSTRAP_SOURCES_PROFILE" (i.e. <tt>jam -sHAIKU_BOOTSTRAP_SOURCES_PROFILE=@release-raw -q @bootstrap-raw</tt> will include source packages for all packages needed by release image).
=== Haiku Architecture Ports ===
When preparing a new Haiku architecture port for the bootstrap build the following things need to be considered:
*There need to be repository definitions "build/jam/repositories/HaikuPorts/<arch>" and "build/jam/repositories/HaikuPortsCross/<arch>". The former lists the packages available for a regular Haiku, i.e. it must include at least the packages needed for a basic Haiku image that can build third-party packages. The latter lists the available bootstrap third-party packages.
*There needs to be "src/data/package_infos/<arch>/haiku", a package info for the Haiku system package (currently also used for the bootstrap package).
*In the haikuports.cross repository all build recipes need to support the architecture (the architecture must be listed in the "ARCHITECTURES" variable). Some software may need to be patched for cross-building to work for the architecture.
*In the haikuports repository all build recipes for required software need to support the architecture.
If the Haiku architecture port doesn't support a working userland yet, the process obviously cannot go further than building the bootstrap Haiku image.
docs/develop/packages/BuildingPackages.rst
+287
View File
@@ -0,0 +1,287 @@
=================
Building Packages
=================
This page provides information regarding the package building process. The first
section documents building a package with the low level command ``package``. The
second section refers to building packages with the ``haikuporter`` tool.
Building a Package with the "package" Command
=============================================
The package file format is specified in detail in a `separate document`_. This
section presents information from the perspective of how to build a package file
with the ``package`` command.
.. _separate document: FileFormat.rst
An hpkg file is an archive file (just like tar or zip files) that additionally
contains package meta information in a separate section of the file. When
building an hpkg file via the ``package`` command the meta information must be
provided via a ``.PackageInfo`` file. For convenience, the file itself is added
to the archive as well and can be extracted later, but it will be ignored by
packagefs.
The ``.PackageInfo`` file must be located in the top directory that is archived.
A ``package`` invocation usually looks like that::
package create -C foo-4.5.26-1 foo-4.5.26-1-x86.hpkg
or (packaging a gcc2 build from within the folder)::
cd foo-4.5.26-1
package create ../foo-4.5.26-1-x86_gcc2.hpkg
The argument of the ``-C`` option specifies the directory whose contents to
archive (by default the current directory), the remaining argument is the path
of the package file to be built.
The .PackageInfo
----------------
The contents of the ``.PackageInfo`` adheres to a restricted driver settings
syntax. It consists of name-value pairs, following this simple grammar::
package_info ::= attribute*
attribute ::= name value_list
value_list ::= value | ( "{" value* "}" )
value ::= value_item+ ( '\n' | ';' )
``name`` can be one of the attribute names defined below. ``value_item`` is
either an unquoted string not containing any whitespace characters or a string
enclosed in quotation marks (``"`` or ``'``) which can contain whitespace and
also escaped characters (using ``\``).
The supported attributes are:
- ``name``: The name of the package, not including the package version. Must
only contain ``entity_name_char`` characters.
::
entity_name_char ::= any character but '-', '/', '=', '!', '<', '>', or whitespace
- ``version``: The version of the package. The string must have the ``version``
format (see the `Version Strings`_ section).
- ``architecture``: The system architecture the package has been built for. Can
be either of:
- ``any``: Any architecture (e.g. a documentation package).
- ``x86``: Haiku x86, built with gcc 4.
- ``x86_gcc2``: Haiku x86, built with gcc 2.
- ``summary``: A short (one-line) description of the package.
- ``description``: A longer description of the package.
- ``vendor``: The name of the person/organization publishing this package.
- ``packager``: The name and e-mail address of person that created this package
(e.g. "Peter Packman <[email protected]>").
- ``copyrights``: A list of copyrights applying to the software contained in
this package.
- ``licenses``: A list of names of the licenses applying to the software
contained in this package.
- ``urls``: A list of URLs referring to the packaged software's project home
page. The list elements can be regular URLs or email-like named URLs (e.g.
"Project Foo <http://foo.example.com>").
- ``source-urls``: A list of URLs referring to the packaged software's source
code or build instructions. Elements have the same format as those of
``urls``.
- ``flags``: A list of boolean flags applying to the package. Can contain any
of the following:
- ``approve_license``: This package's license requires approval (i.e. must be
shown to and acknowledged by user before installation).
- ``system_package``: This is a system package (i.e. lives under
"/boot/system").
- ``provides``: A list of entities provided by this package. The list elements
must have the following format::
entity ::= entity_name [ "=" version_ref ] [ ( "compat" | "compatible" ) ">=" version_ref ]
entity_name ::= [ entity_type ":" ] entity_name_char+
entity_type ::= "lib" | "cmd" | "app" | "add_on"
See the `Version Strings`_ section for the ``version_ref`` definition.
The first ``version_ref`` specifies the version of the provided entity. It
can be omitted e.g. for abstract resolvables like "web_browser". The
``version_ref`` after the "compat"/"compatible" string specifies the oldest
version the resolvable is backwards compatible with.
The ``entity_type`` specifies the type of entity provided: a library ("lib"),
a command line program ("cmd"), an application ("app"), or an add-on
("add-on").
- ``requires``: A list of entities required by this package. The list elements
must have the following format::
required_entity ::= entity_name [ version_operator version_ref [ "base" ] ]
version_operator ::= "<" | "<=" | "==" | "!=" | ">=" | ">"
See the `Version Strings`_ section for the ``version_ref`` definition. If
"base" is specified, the specified entity is the base package for this
package. The package manager shall ensure that this package is installed in
the same installation location as its base package.
- ``supplements``: A list of entities that are supplemented by this package
(i.e. this package will automatically be selected for installation if the
supplemented entities are already installed). The list elements must have the
``required_entity`` format.
- ``conflicts``: A list of entities that this package conflicts with (i.e. only
one of both can be installed at any time). The list elements must have the
``required_entity`` format.
- ``freshens``: A list of entities that are being freshened by this package
(i.e. this package will patch one or more files of the package(s) that provide
this entity). The list elements must have the ``required_entity`` format.
- ``replaces``: A list of entities that are being replaced by this package (used
if the name of a package changes, or if a package has been split). The list
elements must have the ``entity_name`` format.
- ``global-writable-files``: A list of global writable file infos. The list
elements must have the following format::
global_writable_file_info ::= path [ "directory" ] [ "keep-old" | "manual" | "auto-merge" ]
``path`` is the relative path of the writable file or directory, starting with
"settings/" or any other writable directory. If the "directory" keyword is
given, the path refers to a directory. If no other keyword is given after the
path respectively after the "directory" keyword, the file or directory is not
included in the package. It will be created by the software or by the user.
If a keyword is given, the file or directory (a default version) is included
in the package and it will be extracted on package activation. The keyword
specifies what shall happen when the package is updated and a previous default
version of the file or directory has been modified by the user:
- "keep-old": Indicates that the software can read old files and the
user-modified file or directory should be kept.
- "manual": Indicates that the software may not be able to read an older file
and the user may have to manually adjust it.
- "auto-merge": Indicates that the file format is simple text and a three-way
merge shall be attempted (not applicable for directories).
- ``user-settings-files``: A list of user settings file infos. The list elements
must have the following format::
user_settings_file_info ::= path [ "directory" | "template" template_path ]
``path`` is the relative path of the settings file or directory, starting with
"settings/". It is not included in the package. However, if ``template_path``
is specified, it is a path to a file included in the package that can serve as
a template for the settings file. It doesn't imply any automatic action on
package activation, though. If the "directory" keyword is given, the path
refers to a settings directory (typical when a program creates multiple
settings files).
- ``users``: A list of specifications for Unix users the packaged software
requires. The list elements must have the following format::
user: ::= name [ "real-name" real_name ] "home" home_path [ "shell" shell_path ] [ "groups" group+ ]
``name`` is the name of the Unix user, ``real_name``, if specified, the real
name of the user, ``home_path`` the path to the user's home directory,
``shell_path`` the path to the user's shell, and ``group`` the name of a Unix
group the users is a member of. If the respective components are not
specified, ``name`` is also used as the user's real name, "/bin/bash" is the
path of the user's shell, and the user will belong to the default user group.
- ``groups``: A list of names of Unix groups the packaged software requires.
- ``post-install-scripts``: A list of paths of files included in the package,
which shall be executed on package activation. Each path must start with
"boot/post-install/".
Version Strings
---------------
Versions strings are used in three contexts: For the package version, for
resolvable versions (``provides``), and in dependency version expressions
(``requires``, ``supplements``, ``conflicts``, ``freshens``). They are
structurally identical, with the exception that the former requires a revision
component (``version``), while the latter two don't (``version_ref``)::
version ::= major [ "." minor [ "." micro ] ] [ "~" pre_release ] "-" revision
version_ref ::= major [ "." minor [ "." micro ] ] [ "~" pre_release ] [ "-" revision ]
major ::= alphanum_underline+
minor ::= alphanum_underline+
micro ::= alphanum_underline_dot+
pre_release ::= alphanum_underline_dot+
revision ::= positive_non_zero_integer
The meaning of the major, minor, and micro version parts is vendor specific. A
typical, but not universal (!), convention is to increment the major version
when breaking binary compatibility (i.e. version a.d.e is backwards compatible
to version a.b.c for all b.c <= d.e), to increment the minor version when adding
new features (in a binary compatible way), and to increment the micro version
for bug fix releases. There are, however, projects that use different
conventions which don't imply that e.g. version 1.4 is backwards compatible with
version 1.2. Which convention is used is important for the packager to know, as
it is required for a correct declaration of the compatibility versions for the
provided resolvables. The compatibility version specifies the oldest version the
provided resolvable is backwards compatible with, thus implying the version
range requested by a dependent package the resolvable can satisfy. When
following the aforementioned convention a resolvable of version 2.4.3 should
have compatibility version 2 (or, semantically virtually identical, 2.0.0).
Not following the convention 2.4 may be correct instead. If no compatibility
version is specified, the resolvable can only satisfy dependency constraints
with an exactly matching version.
The pre-release part of the version string has special semantics for comparison.
Unlike minor and micro its presence makes the version older. E.g. version
R1.0~alpha1 is considered to be older than version R1.0. When both version
strings have a pre-release part, that part is compared naturally after the micro
part (R1.0.1~alpha1 > R1.0 > R1.0~beta1 > R1.0~alpha2).
The revision part of the version string is assigned by the packager (not by the
vendor). It allows to uniquely identify updated packages of the same vendor
version of a software.
Package File Names
------------------
A package file name should have the following form::
file_name ::= name "-" version "-" architecture ".hpkg"
Example package file
--------------------
::
name example
version 42.17-12
architecture x86_gcc2
summary "This is an example package file"
description "Haiku has a very powerful package management system. Really, you should try it!
it even supports muliline strings in package descriptions"
packager "John Doe <[email protected]>"
vendor "Haiku Project"
licenses {
"MIT"
}
copyrights {
"Copyright (C) 1812-2013 by John Doe <[email protected]>"
}
provides {
example = 42.17-12
cmd:example = 3.1
}
requires {
haiku >= r1~alpha4_pm_hrev46213-1
lib:libpython2.6 >= 1.0
}
urls {
"http://example.com/"
}
global-writable-files {
"settings/example/configurationFile" keep-old
"settings/example/servers" directory keep-old
}
source-urls {
"Download <http://example.com/source.zip>"
}
Building a Package with "haikuporter"
=====================================
``haikuporter`` is a high level tool for building packages. As input it reads a
build recipe file for a certain version of a software (aka port) and produces
one or more packages, as declared in the recipe. A recipe specifies package
requirements similar to how it is done in a ``.PackageInfo`` file. When asked to
build a port, ``haikuporter`` resolves the respective dependencies and
recursively builds all not-yet-built ports required for the requested port.
``haikuporter`` itself and a large library of recipe files are hosted at
HaikuPorts_. A detailed `documentation for haikuporter`_ and the
`recipe format`_ can also be found there.
.. _HaikuPorts: https://github.com/haikuports/
.. _documentation for haikuporter:
https://github.com/haikuports/haikuports/wiki/HaikuPorterForPM
.. _recipe format:
https://github.com/haikuports/haikuports/wiki/HaikuPorter-BuildRecipes
docs/develop/packages/BuildingPackages.wiki
-162
View File
@@ -1,162 +0,0 @@
== Building Packages ==
This page provides information regarding the package building process. The first section documents building a package with the low level command <tt>package</tt>. The second section refers to building packages with the <tt>haikuporter</tt> tool.
=== Building a Package with the "package" Command ===
The package file format is specified in detail in a [[PackageManagement/FileFormat| separate document]]. This section presents information from the perspective of how to build a package file with the <tt>package</tt> command.
An hpkg file is an archive file (just like tar or zip files) that additionally contains package meta information in a separate section of the file. When building an hpkg file via the <tt>package</tt> command the meta information must be provided via a <tt>.PackageInfo</tt> file. For convenience, the file itself is added to the archive as well and can be extracted later, but it will be ignored by packagefs.
The <tt>.PackageInfo</tt> file must be located in the top directory that is archived. A <tt>package</tt> invocation usually looks like that:
<pre>
package create -C foo-4.5.26-1 foo-4.5.26-1-x86.hpkg
</pre>
or (packaging a gcc2 build from within the folder):
<pre>
cd foo-4.5.26-1
package create ../foo-4.5.26-1-x86_gcc2.hpkg
</pre>
The argument of the <tt>-C</tt> option specifies the directory whose contents to archive (by default the current directory), the remaining argument is the path of the package file to be built.
==== The .PackageInfo ====
The contents of the <tt>.PackageInfo</tt> adheres to a restricted driver settings syntax. It consists of name-value pairs, following this simple grammar:
<pre>
package_info ::= attribute*
attribute ::= name value_list
value_list ::= value | ( "{" value* "}" )
value ::= value_item+ ( '\n' | ';' )
</pre>
<tt>name</tt> can be one of the attribute names defined below. <tt>value_item</tt> is either an unquoted string not containing any whitespace characters or a string enclosed in quotation marks (<tt>"</tt> or <tt>'</tt>) which can contain whitespace and also escaped characters (using <tt>\</tt>).
The supported attributes are:
*<tt>name</tt>: The name of the package, not including the package version. Must only contain <tt>entity_name_char</tt> characters.
<pre>
entity_name_char ::= any character but '-', '/', '=', '!', '<', '>', or whitespace
</pre>
*<tt>version</tt>: The version of the package. The string must have the <tt>version</tt> format (see the [[PackageManagement/BuildingPackages#VersionStrings| Version Strings]] section).
*<tt>architecture</tt>: The system architecture the package has been built for. Can be either of:
- <tt>any</tt>: Any architecture (e.g. a documentation package).
- <tt>x86</tt>: Haiku x86, built with gcc 4.
- <tt>x86_gcc2</tt>: Haiku x86, built with gcc 2.
*<tt>summary</tt>: A short (one-line) description of the package.
*<tt>description</tt>: A longer description of the package.
*<tt>vendor</tt>: The name of the person/organization publishing this package.
*<tt>packager</tt>: The name and e-mail address of person that created this package (e.g. "Peter Packman <[email protected]>").
*<tt>copyrights</tt>: A list of copyrights applying to the software contained in this package.
*<tt>licenses</tt>: A list of names of the licenses applying to the software contained in this package.
*<tt>urls</tt>: A list of URLs referring to the packaged software's project home page. The list elements can be regular URLs or email-like named URLs (e.g. "Project Foo <http://foo.example.com>").
*<tt>source-urls</tt>: A list of URLs referring to the packaged software's source code or build instructions. Elements have the same format as those of <tt>urls</tt>.
*<tt>flags</tt>: A list of boolean flags applying to the package. Can contain any of the following:
- <tt>approve_license</tt>: This package's license requires approval (i.e. must be shown to and acknowledged by user before installation).
- <tt>system_package</tt>: This is a system package (i.e. lives under "/boot/system") .
*<tt>provides</tt>: A list of entities provided by this package. The list elements must have the following format:
<pre>
entity ::= entity_name [ "=" version_ref ] [ ( "compat" | "compatible" ) ">=" version_ref ]
entity_name ::= [ entity_type ":" ] entity_name_char+
entity_type ::= "lib" | "cmd" | "app" | "add_on"
</pre>
See the [[PackageManagement/BuildingPackages#VersionStrings| Version Strings]] section for the <tt>version_ref</tt> definition.
The first <tt>version_ref</tt> specifies the version of the provided entity. It can be omitted e.g. for abstract resolvables like "web_browser". The <tt>version_ref</tt> after the "compat"/"compatible" string specifies the oldest version the resolvable is backwards compatible with.
The <tt>entity_type</tt> specifies the type of entity provided: a library ("lib"), a command line program ("cmd"), an application ("app"), or an add-on ("add-on").
*<tt>requires</tt>: A list of entities required by this package. The list elements must have the following format:
<pre>
required_entity ::= entity_name [ version_operator version_ref [ "base" ] ]
version_operator ::= "<" | "<=" | "==" | "!=" | ">=" | ">"
</pre>
See the [[PackageManagement/BuildingPackages#VersionStrings| Version Strings]] section for the <tt>version_ref</tt> definition. If "base" is specified, the specified entity is the base package for this package. The package manager shall ensure that this package is installed in the same installation location as its base package.
*<tt>supplements</tt>: A list of entities that are supplemented by this package (i.e. this package will automatically be selected for installation if the supplemented entities are already installed). The list elements must have the <tt>required_entity</tt> format.
*<tt>conflicts</tt>: A list of entities that this package conflicts with (i.e. only one of both can be installed at any time). The list elements must have the <tt>required_entity</tt> format.
*<tt>freshens</tt>: A list of entities that are being freshened by this package (i.e. this package will patch one or more files of the package(s) that provide this entity). The list elements must have the <tt>required_entity</tt> format.
*<tt>replaces</tt>: A list of entities that are being replaced by this package (used if the name of a package changes, or if a package has been split). The list elements must have the <tt>entity_name</tt> format.
*<tt>global-writable-files</tt>: A list of global writable file infos. The list elements must have the following format:
<pre>
global_writable_file_info ::= path [ "directory" ] [ "keep-old" | "manual" | "auto-merge" ]
</pre>
<tt>path</tt> is the relative path of the writable file or directory, starting with "settings/" or any other writable directory. If the "directory" keyword is given, the path refers to a directory. If no other keyword is given after the path respectively after the "directory" keyword, the file or directory is not included in the package. It will be created by the software or by the user. If a keyword is given, the file or directory (a default version) is included in the package and it will be extracted on package activation. The keyword specifies what shall happen when the package is updated and a previous default version of the file or directory has been modified by the user:
- "keep-old": Indicates that the software can read old files and the user-modified file or directory should be kept.
- "manual": Indicates that the software may not be able to read an older file and the user may have to manually adjust it.
- "auto-merge": Indicates that the file format is simple text and a three-way merge shall be attempted (not applicable for directories).
*<tt>user-settings-files</tt>: A list of user settings file infos. The list elements must have the following format:
<pre>
user_settings_file_info ::= path [ "directory" | "template" template_path ]
</pre>
<tt>path</tt> is the relative path of the settings file or directory, starting with "settings/". It is not included in the package. However, if <tt>template_path</tt> is specified, it is a path to a file included in the package that can serve as a template for the settings file. It doesn't imply any automatic action on package activation, though. If the "directory" keyword is given, the path refers to a settings directory (typical when a program creates multiple settings files).
*<tt>users</tt>: A list of specifications for Unix users the packaged software requires. The list elements must have the following format:
<pre>
user: ::= name [ "real-name" real_name ] "home" home_path [ "shell" shell_path ] [ "groups" group+ ]
</pre>
<tt>name</tt> is the name of the Unix user, <tt>real_name</tt>, if specified, the real name of the user, <tt>home_path</tt> the path to the user's home directory, <tt>shell_path</tt> the path to the user's shell, and <tt>group</tt> the name of a Unix group the users is a member of. If the respective components are not specified, <tt>name</tt> is also used as the user's real name, "/bin/bash" is the path of the user's shell, and the user will belong to the default user group.
*<tt>groups</tt>: A list of names of Unix groups the packaged software requires.
*<tt>post-install-scripts</tt>: A list of paths of files included in the package, which shall be executed on package activation. Each path must start with "boot/post-install/".
==== Version Strings ====
Versions strings are used in three contexts: For the package version, for resolvable versions (<tt>provides</tt>), and in dependency version expressions (<tt>requires</tt>, <tt>supplements</tt>, <tt>conflicts</tt>, <tt>freshens</tt>). They are structurally identical, with the exception that the former requires a revision component (<tt>version</tt>), while the latter two don't (<tt>version_ref</tt>):
<pre>
version ::= major [ "." minor [ "." micro ] ] [ "~" pre_release ] "-" revision
version_ref ::= major [ "." minor [ "." micro ] ] [ "~" pre_release ] [ "-" revision ]
major ::= alphanum_underline+
minor ::= alphanum_underline+
micro ::= alphanum_underline_dot+
pre_release ::= alphanum_underline_dot+
revision ::= positive_non_zero_integer
</pre>
The meaning of the major, minor, and micro version parts is vendor specific. A typical, but not universal (!), convention is to increment the major version when breaking binary compatibility (i.e. version a.d.e is backwards compatible to version a.b.c for all b.c <= d.e), to increment the minor version when adding new features (in a binary compatible way), and to increment the micro version for bug fix releases. There are, however, projects that use different conventions which don't imply that e.g. version 1.4 is backwards compatible with version 1.2. Which convention is used is important for the packager to know, as it is required for a correct declaration of the compatibility versions for the provided resolvables. The compatibility version specifies the oldest version the provided resolvable is backwards compatible with, thus implying the version range requested by a dependent package the resolvable can satisfy. When following the aforementioned convention a resolvable of version 2.4.3 should have compatibility version 2 (or, semantically virtually identical, 2.0.0). Not following the convention 2.4 may be correct instead. If no compatibility version is specified, the resolvable can only satisfy dependency constraints with an exactly matching version.
The pre-release part of the version string has special semantics for comparison. Unlike minor and micro its presence makes the version older. E.g. version R1.0~alpha1 is considered to be older than version R1.0. When both version strings have a pre-release part, that part is compared naturally after the micro part (R1.0.1~alpha1 > R1.0 > R1.0~beta1 > R1.0~alpha2).
The revision part of the version string is assigned by the packager (not by the vendor). It allows to uniquely identify updated packages of the same vendor version of a software.
==== Package File Names ====
A package file name should have the following form:
<pre>
file_name ::= name "-" version "-" architecture ".hpkg"
</pre>
==== Example package file ====
<pre>
name example
version 42.17-12
architecture x86_gcc2
summary "This is an example package file"
description "Haiku has a very powerful package management system. Really, you should try it!
it even supports muliline strings in package descriptions"
packager "John Doe <[email protected]>"
vendor "Haiku Project"
licenses {
"MIT"
}
copyrights {
"Copyright (C) 1812-2013 by John Doe <[email protected]>"
}
provides {
example = 42.17-12
cmd:example = 3.1
}
requires {
haiku >= r1~alpha4_pm_hrev46213-1
lib:libpython2.6 >= 1.0
}
urls {
"http://example.com/"
}
global-writable-files {
"settings/example/configurationFile" keep-old
"settings/example/servers" directory keep-old
}
source-urls {
"Download <http://example.com/source.zip>"
}
</pre>
=== Building a Package with "haikuporter" ===
<tt>haikuporter</tt> is a high level tool for building packages. As input it reads a build recipe file for a certain version of a software (aka port) and produces one or more packages, as declared in the recipe. A recipe specifies package requirements similar to how it is done in a <tt>.PackageInfo</tt> file. When asked to build a port, <tt>haikuporter</tt> resolves the respective dependencies and recursively builds all not-yet-built ports required for the requested port. <tt>haikuporter</tt> itself and a large library of recipe files are hosted at [https://github.com/haikuports/ HaikuPorts]. A detailed [https://github.com/haikuports/haikuports/wiki/HaikuPorterForPM documentation for haikuporter] and the [https://github.com/haikuports/haikuports/wiki/HaikuPorter-BuildRecipes recipe format] can also be found there.
docs/develop/packages/DirectoryStructure.rst
+61
View File
@@ -0,0 +1,61 @@
===============================
Boot Volume Directory Structure
===============================
This is the directory layout of the boot volume::
home/config
<like system, but without haiku_loader, kernel_<arch>, and runtime_loader>
system
add-ons
apps
bin
boot
cache*
data
demos
develop
documentation
lib
non-packaged*
packages*
preferences
servers
settings*
var*
haiku_loader
kernel_<arch>
runtime_loader
trash
The structure mostly equals the pre-package management directory structure with
the following changes:
- ``common`` has been removed, or more correctly it has been merged into
``system``. All system-wide software is now installed (only) in ``system``.
- The ``develop`` directory has been removed and its contents has been moved to
the ``system/develop`` directory.
- The ``include`` directory has been removed. Its contents lives in
``develop/headers`` now.
- ``optional`` has been removed. Optional features can just be installed via the
package manager.
- ``share`` and ``etc`` (in ``common``) have been removed. Their contents goes
to ``data``, ``documentation``, or ``settings`` (in ``system`` or, for
packages installed there, in ``home``) as appropriate. There's
``settings/etc`` which is where ported Unix software will usually store their
global settings.
- ``apps`` and ``preferences`` have been moved to ``system`` for consistency.
- ``system`` and ``home/config`` each sport a ``packages`` directory, which
contains the activated packages.
- ``system`` and ``home/config`` themselves are mount points for two instances
of the packagefs, i.e. each contains the virtually extracted contents of the
activated packages in the respective ``packages`` subdirectory. The
directories marked with ``*`` are "shine-through" directories. They are not
provided by the packagefs, but are the underlying directories of the boot
volume. Unlike the other directories they are writable.
- ``system`` and ``home/config`` each contain a directory ``non-packaged``
which has the same structure as their parent directory minus the shine-through
directories. In the ``non-packaged`` directories software can be installed the
traditional -- non-packaged -- way.
docs/develop/packages/DirectoryStructure.wiki
-44
View File
@@ -1,44 +0,0 @@
== Boot Volume Directory Structure ==
This is the directory layout of the boot volume:
<pre>
home/config
<like system, but without haiku_loader, kernel_<arch>, and runtime_loader>
system
add-ons
apps
bin
boot
cache*
data
demos
develop
documentation
lib
non-packaged*
packages*
preferences
servers
settings*
var*
haiku_loader
kernel_<arch>
runtime_loader
trash
</pre>
The structure mostly equals the pre-package management directory structure with the following changes:
*<tt>common</tt> has been removed, or more correctly it has been merged into <tt>system</tt>. All system-wide software is now installed (only) in <tt>system</tt>.
*The <tt>develop</tt> directory has been removed and its contents has been moved to the <tt>system/develop</tt> directory.
*The <tt>include</tt> directory has been removed. Its contents lives in <tt>develop/headers</tt> now.
*<tt>optional</tt> has been removed. Optional features can just be installed via the package manager.
*<tt>share</tt> and <tt>etc</tt> (in <tt>common</tt>) have been removed. Their contents goes to <tt>data</tt>, <tt>documentation</tt>, or <tt>settings</tt> (in <tt>system</tt> or, for packages installed there, in <tt>home</tt>) as appropriate. There's <tt>settings/etc</tt> which is where ported Unix software will usually store their global settings.
*<tt>apps</tt> and <tt>preferences</tt> have been moved to <tt>system</tt> for consistency.
*<tt>system</tt> and <tt>home/config</tt> each sport a <tt>packages</tt> directory, which contains the activated packages.
*<tt>system</tt> and <tt>home/config</tt> themselves are mount points for two instances of the packagefs, i.e. each contains the virtually extracted contents of the activated packages in the respective <tt>packages</tt> subdirectory. The directories marked with <tt>*</tt> are "shine-through" directories. They are not provided by the packagefs, but are the underlying directories of the boot volume. Unlike the other directories they are writable.
*<tt>system</tt> and <tt>home/config</tt> each contain a directory <tt>non-packaged</tt> which has the same structure as their parent directory minus the shine-through directories. In the <tt>non-packaged</tt> directories software can be installed the traditional -- non-packaged -- way.
docs/develop/packages/FileFormat.rst
+1046
View File
File diff suppressed because it is too large Load Diff
docs/develop/packages/FileFormat.wiki
-959
View File
@@ -1,959 +0,0 @@
== Haiku Package File Format ==
This document specifies the Haiku Package (HPKG) file format, which was designed for efficient use by Haiku's package file system. It is somewhat inspired by the [http://code.google.com/p/xar/ XAR format] (separate TOC and data heap), but aims for greater compactness (no XML for the TOC).
Three stacked format layers can be identified:
- A generic container format for structured data.
- An archive format specifying how file system data are stored in the container.
- A package format, extending the archive format with attributes for package management.
=== The Data Container Format ===
A HPKG file consists of four sections:
Header::
Identifies the file as HPKG file and provides access to the other sections.
Heap::
Contains arbitrary (mostly unstructured) data referenced by the next two
sections.
TOC (table of contents)::
The main section, containing structured data with references to unstructured
data in the heap section.
Package Attributes::
A section similar to the TOC. Rather than describing the data contained in
the file, it specifies meta data of the package as a whole.
The TOC and Package Attributes sections aren't really separate sections, as they are stored at the end of the heap.
All numbers in the HPKG are stored in big endian format or [http://en.wikipedia.org/wiki/LEB128 LEB128] encoding.
==== Header ====
The header has the following structure:
<pre>
struct hpkg_header {
uint32 magic;
uint16 header_size;
uint16 version;
uint64 total_size;
uint16 minor_version;
uint16 heap_compression;
uint32 heap_chunk_size;
uint64 heap_size_compressed;
uint64 heap_size_uncompressed;
uint32 attributes_length;
uint32 attributes_strings_length;
uint32 attributes_strings_count;
uint32 reserved1;
uint64 toc_length;
uint64 toc_strings_length;
uint64 toc_strings_count;
};
</pre>
magic::
The string 'hpkg' (B_HPKG_MAGIC).
header_size::
The size of the header. This is also the absolute offset of the heap.
version::
The version of the HPKG format the file conforms to. The current version is
2 (B_HPKG_VERSION).
total_size::
The total file size.
minor_version::
The minor version of the HPKG format the file conforms to. The current minor version is
0 (B_HPKG_MINOR_VERSION). Additions of new attributes to the attributes or TOC sections should
generally only increment the minor version. When a file with a greater minor version is
encountered, the reader should ignore unknown attributes.
heap_compression::
Compression format used for the heap.
heap_chunk_size::
The size of the chunks the uncompressed heap data are divided into.
heap_size_compressed::
The compressed size of the heap. This includes all administrative data (the chunk size array).
heap_size_uncompressed::
The uncompressed size of the heap. This is only the size of the raw data (including the TOC
and attributes section), not including administrative data (the chunk size array).
attributes_length::
The uncompressed size of the package attributes section.
attributes_strings_length::
The size of the strings subsection of the package attributes section.
attributes_strings_count::
The number of entries in the strings subsection of the package attributes section.
reserved1::
Reserved for later use.
toc_length::
The uncompressed size of the TOC section.
toc_strings_length::
The size of the strings subsection of the TOC section.
toc_strings_count::
The number of entries in the strings subsection of the TOC section.
==== Heap ====
The heap provides storage for arbitrary data. Data from various sources are concatenated without padding or separator, forming the uncompressed heap. A specific section of data is usually referenced (e.g. in the TOC and attributes sections) by an offset and the number of bytes. These references always point into the uncompressed heap, even if the heap is actually stored in a compressed format. The <tt>heap_compression</tt> field in the header specifies which format is used. The following values are defined:
{| border=1 class="simple"
!0
!B_HPKG_COMPRESSION_NONE
!no compression
|-
| 1
| B_HPKG_COMPRESSION_ZLIB
| zlib (LZ77) compression
|}
The uncompressed heap data are divided into equally sized chunks (64 KiB). The last chunk in the heap may have a different uncompressed length from the preceding chunks. The uncompressed length of the last chunk can be derived. Each individual chunk may be stored compressed or not.
Unless B_HPKG_COMPRESSION_NONE is specified, a uint16 array at the end of the heap contains the actual in-file (compressed) size of each chunk (minus 1 -- 0 means 1 byte), save for the last one, which is omitted since it is implied. A chunk is only stored compressed, if compression actually saves space. That is if the chunk's compressed size equals its uncompressed size, the data aren't compressed. If B_HPKG_COMPRESSION_NONE is specified, the chunk size table is omitted entirely.
The TOC and the package attributes sections are stored (in this order) at the end of the uncompressed heap. The offset of the package attributes section data is therefore <tt>heap_size_uncompressed - attributes_length</tt> and the offset of the TOC section data <tt>heap_size_uncompressed - attributes_length - toc_length</tt>.
==== TOC ====
The TOC section contains a list of attribute trees. An attribute has an ID, a data type, and a value, and can have child attributes. E.g.:
- ATTRIBUTE_ID_SHOPPING_LIST : string : "bakery"
- ATTRIBUTE_ID_ITEM : string : "rye bread"
- ATTRIBUTE_ID_ITEM : string : "bread roll"
- ATTRIBUTE_ID_COUNT : int : 10
- ATTRIBUTE_ID_ITEM : string : "cookie"
- ATTRIBUTE_ID_COUNT : int : 5
- ATTRIBUTE_ID_SHOPPING_LIST : string : "hardware store"
- ATTRIBUTE_ID_ITEM : string : "hammer"
- ATTRIBUTE_ID_ITEM : string : "nail"
- ATTRIBUTE_ID_SIZE : int : 10
- ATTRIBUTE_ID_COUNT : int : 100
The main TOC section refers to any attribute by its unique ID (see below) and stores the attribute's value, either as a reference into the heap or as inline data.
An optimization exists for shared string attribute values. A string value used by more than one attribute is stored in the strings subsection and is referenced by an index.
Hence the TOC section consists of two subsections:
Strings::
A table of commonly used strings.
Main TOC::
The attribute trees.
==== Attribute Data Types ====
These are the specified data type values for attributes:
{| border=1 class="simple"
!0
!B_HPKG_ATTRIBUTE_TYPE_INVALID
!invalid
|-
| 1
| B_HPKG_ATTRIBUTE_TYPE_INT
| signed integer
|-
| 2
| B_HPKG_ATTRIBUTE_TYPE_UINT
| unsigned integer
|-
| 3
| B_HPKG_ATTRIBUTE_TYPE_STRING
| UTF-8 string
|-
| 4
| B_HPKG_ATTRIBUTE_TYPE_RAW
| raw data
|}
==== Strings ====
The strings subsections consists of a list of null-terminated UTF-8 strings. The section itself is terminated by a 0 byte.
Each string is implicitly assigned the (null-based) index at which it appears in the list, i.e. the nth string has the index n - 1. The string is referenced by this index in the main TOC subsection.
==== Main TOC ====
The main TOC subsection consists of a list of attribute entries terminated by a 0 byte. An attribute entry is stored as:
Attribute tag::
An unsigned LEB128 encoded number.
Attribute value::
The value of the attribute encoded as described below.
Attribute child list::
Only if this attribute is marked to have children: A list of attribute
entries terminated by a 0 byte.
The attribute tag encodes four pieces of information:
<tt>(encoding << 11) + (hasChildren << 10) + (dataType << 7) + id + 1</tt>
encoding::
Specifies the encoding of the attribute value as described below.
hasChildren::
1, if the attribute has children, 0 otherwise.
dataType::
The data type of the attribute (B_HPKG_ATTRIBUTE_TYPE_...).
id::
The ID of the attribute (B_HPKG_ATTRIBUTE_ID_...).
==== Attribute Values ====
A value of each of the data types can be encoded in different ways, which is defined by the encoding value:
- B_HPKG_ATTRIBUTE_TYPE_INT and B_HPKG_ATTRIBUTE_TYPE_UINT:
{| border=1 class="simple"
!0
!B_HPKG_ATTRIBUTE_ENCODING_INT_8_BIT
!int8/uint8
|-
!1
!B_HPKG_ATTRIBUTE_ENCODING_INT_16_BIT
!int16/uint16
|-
!2
!B_HPKG_ATTRIBUTE_ENCODING_INT_32_BIT
!int32/uint32
|-
!3
!B_HPKG_ATTRIBUTE_ENCODING_INT_64_BIT
!int64/uint64
|}
- B_HPKG_ATTRIBUTE_TYPE_STRING:
{| border=1 class="simple"
!0
!B_HPKG_ATTRIBUTE_ENCODING_STRING_INLINE
!null-terminated UTF-8 string
|-
!1
!B_HPKG_ATTRIBUTE_ENCODING_STRING_TABLE
!unsigned LEB128: index into string table
|}
- B_HPKG_ATTRIBUTE_TYPE_RAW
{| border=1 class="simple"
!0
!B_HPKG_ATTRIBUTE_ENCODING_RAW_INLINE
!unsigned LEB128: size; followed by raw bytes
|-
!1
!B_HPKG_ATTRIBUTE_ENCODING_RAW_HEAP
!unsigned LEB128: size; unsigned LEB128: offset into the uncompressed heap
|}
==== Package Attributes ====
The package attributes section contains a list of attribute trees, just like
the TOC section. The structure of this section follows the TOC, i.e. there's a subsection for shared strings and a subsection that stores a list of attribute entries terminated by a 0 byte. An entry has the same format as the ones in the TOC (only using different attribute IDs).
=== The Archive Format ===
This section specifies how file system objects (files, directories, symlinks) are stored in a HPKG file. It builds on top of the container format, defining the types of attributes, their order, and allowed values.
E.g. a "bin" directory, containing a symlink and a file:
<pre>
bin 0 2009-11-13 12:12:09 drwxr-xr-x
awk 0 2009-11-13 12:11:16 lrwxrwxrwx -> gawk
gawk 301699 2009-11-13 12:11:16 -rwxr-xr-x
</pre>
could be represented by this attribute tree:
- B_HPKG_ATTRIBUTE_ID_DIR_ENTRY : string : "bin"
- B_HPKG_ATTRIBUTE_ID_FILE_TYPE : uint : 1 (0x1)
- B_HPKG_ATTRIBUTE_ID_FILE_MTIME : uint : 1258110729 (0x4afd3f09)
- B_HPKG_ATTRIBUTE_ID_DIR_ENTRY : string : "awk"
- B_HPKG_ATTRIBUTE_ID_FILE_TYPE : uint : 2 (0x2)
- B_HPKG_ATTRIBUTE_ID_FILE_MTIME : uint : 1258110676 (0x4afd3ed4)
- B_HPKG_ATTRIBUTE_ID_SYMLINK_PATH : string : "gawk"
- B_HPKG_ATTRIBUTE_ID_DIR_ENTRY : string : "gawk"
- B_HPKG_ATTRIBUTE_ID_FILE_PERMISSIONS : uint : 493 (0x1ed)
- B_HPKG_ATTRIBUTE_ID_FILE_MTIME : uint : 1258110676 (0x4afd3ed4)
- B_HPKG_ATTRIBUTE_ID_DATA : raw : size: 301699, offset: 0
- B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE : string : "BEOS:APP_VERSION"
- B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE_TYPE : uint : 1095782486 (0x41505056)
- B_HPKG_ATTRIBUTE_ID_DATA : raw : size: 680, offset: 301699
- B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE : string : "BEOS:TYPE"
- B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE_TYPE : uint : 1296649555 (0x4d494d53)
- B_HPKG_ATTRIBUTE_ID_DATA : raw : size: 35, offset: 302379
==== Attribute IDs ====
The following attribute IDs are specified by the archive format. Any other attributes will be ignored.
==== B_HPKG_ATTRIBUTE_ID_DIRECTORY_ENTRY ("dir:entry") ====
* '''Type:''' string
* '''Value:''' File name of the entry.
* '''Allowed Values:''' Any valid file (not path!) name, save "." and "..".
* '''Child Attributes:'''
- B_HPKG_ATTRIBUTE_ID_FILE_TYPE: The file type of the entry.
- B_HPKG_ATTRIBUTE_ID_FILE_PERMISSIONS: The file permissions of the entry.
- B_HPKG_ATTRIBUTE_ID_FILE_USER: The owning user of the entry.
- B_HPKG_ATTRIBUTE_ID_FILE_GROUP: The owning group of the entry.
- B_HPKG_ATTRIBUTE_ID_FILE_ATIME[_NANOS]: The entry's file access time.
- B_HPKG_ATTRIBUTE_ID_FILE_MTIME[_NANOS]: The entry's file modification time.
- B_HPKG_ATTRIBUTE_ID_FILE_CRTIME[_NANOS]: The entry's file creation time.
- B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE: An extended file attribute associated with entry.
- B_HPKG_ATTRIBUTE_ID_DATA: Only if the entry is a file: The file data.
- B_HPKG_ATTRIBUTE_ID_SYMLINK_PATH: Only if the entry is a symlink: The path the symlink points to.
- B_HPKG_ATTRIBUTE_ID_DIRECTORY_ENTRY: Only if the entry is a directory: A child entry in that directory.
==== B_HPKG_ATTRIBUTE_ID_FILE_TYPE ("file:type") ====
* '''Type:''' uint
* '''Value:''' Type of the entry.
* '''Allowed Values:'''
{| border=1 class="simple"
!0
!B_HPKG_FILE_TYPE_FILE
!file
|}
{| border=1 class="simple"
!1
!B_HPKG_FILE_TYPE_DIRECTORY
!directory
|}
{| border=1 class="simple"
!2
!B_HPKG_FILE_TYPE_SYMLINK
!symlink
|}
* '''Default Value:''' B_HPKG_FILE_TYPE_FILE
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_FILE_PERMISSIONS ("file:permissions") ====
* '''Type:''' uint
* '''Value:''' File permissions.
* '''Allowed Values:''' Any valid permission mask.
* '''Default Value:'''
- For files: 0644 (octal).
- For directories: 0755 (octal).
- For symlinks: 0777 (octal).
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_FILE_USER ("file:user") ====
* '''Type:''' string
* '''Value:''' Name of the user owning the file.
* '''Allowed Values:''' Any non-empty string.
* '''Default Value:''' The user owning the installation location where the package is activated.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_FILE_GROUP ("file:group") ====
* '''Type:''' string
* '''Value:''' Name of the group owning the file.
* '''Allowed Values:''' Any non-empty string.
* '''Default Value:''' The group owning the installation location where the package is activated.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_FILE_ATIME ("file:atime") ====
* '''Type:''' uint
* '''Value:''' File access time (seconds since the Epoch).
* '''Allowed Values:''' Any value.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_FILE_ATIME_NANOS ("file:mtime:nanos") ====
* '''Type:''' uint
* '''Value:''' The nano seconds fraction of the file access time.
* '''Allowed Values:''' Any value in [0, 999999999].
* '''Default Value:''' 0
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_FILE_MTIME ("file:mtime") ====
* '''Type:''' uint
* '''Value:''' File modified time (seconds since the Epoch).
* '''Allowed Values:''' Any value.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_FILE_MTIME_NANOS ("file:mtime:nanos") ====
* '''Type:''' uint
* '''Value:''' The nano seconds fraction of the file modified time.
* '''Allowed Values:''' Any value in [0, 999999999].
* '''Default Value:''' 0
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_FILE_CRTIME ("file:crtime") ====
* '''Type:''' uint
* '''Value:''' File creation time (seconds since the Epoch).
* '''Allowed Values:''' Any value.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_FILE_CRTIM_NANOS ("file:crtime:nanos") ====
* '''Type:''' uint
* '''Value:''' The nano seconds fraction of the file creation time.
* '''Allowed Values:''' Any value in [0, 999999999].
* '''Default Value:''' 0
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE ("file:attribute") ====
* '''Type:''' string
* '''Value:''' Name of the extended file attribute.
* '''Allowed Values:''' Any valid attribute name.
* '''Child Attributes:'''
- B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE_TYPE: The type of the file attribute.
- B_HPKG_ATTRIBUTE_ID_DATA: The file attribute data.
==== B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE_TYPE ("file:attribute:type") ====
* '''Type:''' uint
* '''Value:''' Type of the file attribute.
* '''Allowed Values:''' Any value in [0, 0xffffffff].
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_DATA ("data") ====
* '''Type:''' data
* '''Value:''' Raw data of a file or attribute.
* '''Allowed Values:''' Any value.
==== B_HPKG_ATTRIBUTE_ID_SYMLINK_PATH ("symlink:path") ====
* '''Type:''' string
* '''Value:''' The path the symlink refers to.
* '''Allowed Values:''': Any valid symlink path.
* '''Default Value:''': Empty string.
* '''Child Attributes:''' none
==== TOC Attributes ====
The TOC can directly contain any number of attributes of the B_HPKG_ATTRIBUTE_ID_DIRECTORY_ENTRY type, which in turn contain descendant attributes as specified in the previous section. Any other attributes are ignored.
=== The Package Format ===
This section specifies how informative package attributes (package-name, version, provides, requires, ...) are stored in a HPKG file. It builds on top of the container format, defining the types of attributes, their order, and allowed values.
E.g. a ".PackageInfo" file, containing a package description that is being converted into a package file:
<pre>
name mypackage
version 0.7.2-1
architecture x86
summary "is a very nice package"
description "has lots of cool features\nand is written in MyC++"
vendor "Me, Myself & I, Inc."
packager "[email protected]"
copyrights { "(C) 2009-2011, Me, Myself & I, Inc." }
licenses { "Me, Myself & I Commercial License"; "MIT" }
provides {
cmd:me
lib:libmyself = 0.7
}
requires {
haiku >= r1
wget
}
</pre>
could be represented by this attribute tree:
- B_HPKG_ATTRIBUTE_ID_PACKAGE_NAME : string : "mypackage"
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR : string : "0"
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR : string : "7"
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO : string : "2"
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_REVISION : uint : 1
- B_HPKG_ATTRIBUTE_ID_PACKAGE_ARCHITECTURE : uint : 1
- B_HPKG_ATTRIBUTE_ID_PACKAGE_SUMMARY : string : "is a very nice package"
- B_HPKG_ATTRIBUTE_ID_PACKAGE_DESCRIPTION : string : "has lots of cool features\nand is written in MyC++"
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VENDOR : string : "Me, Myself & I, Inc."
- B_HPKG_ATTRIBUTE_ID_PACKAGE_PACKAGER : string : "[email protected]"
- B_HPKG_ATTRIBUTE_ID_PACKAGE_COPYRIGHT : string : "(C) 2009-2011, Me, Myself & I, Inc."
- B_HPKG_ATTRIBUTE_ID_PACKAGE_LICENSE : string : "Me, Myself & I Commercial License"
- B_HPKG_ATTRIBUTE_ID_PACKAGE_LICENSE : string : "MIT"
- B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES : string : "cmd:me"
- B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES : string : "lib:libmyself"
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR : string : "0"
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR : string : "7"
- B_HPKG_ATTRIBUTE_ID_PACKAGE_REQUIRES : string : "haiku"
- B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR : uint : 4
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR : string : "r1"
- B_HPKG_ATTRIBUTE_ID_PACKAGE_REQUIRES : string : "wget"
==== Attribute IDs ====
The following attribute IDs are specified by the package format. Any other attributes will be rejected.
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_NAME ("package:name") ====
* '''Type:''' string
* '''Value:''' Name of the package.
* '''Allowed Values:''' Any string matching <entity_name_char>+, with <entity_name_char> being any character but '-', '/', '=', '!', '<', '>', or whitespace.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_SUMMARY ("package:summary") ====
* '''Type:''' string
* '''Value:''' Short description of the package.
* '''Allowed Values:''' Any single-lined string.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_DESCRIPTION ("package:description") ====
* '''Type:''' string
* '''Value:''' Long description of the package.
* '''Allowed Values:''' Any string (may contain multiple lines).
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_VENDOR ("package:vendor") ====
* '''Type:''' string
* '''Value:''' Name of the person/organization that is publishing this package.
* '''Allowed Values:''' Any single-lined string.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_PACKAGER ("package:packager") ====
* '''Type:''' string
* '''Value:''' E-Mail address of person that created this package.
* '''Allowed Values:''' Any single-lined string, but e-mail preferred.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_BASE_PACKAGE ("package:base-package") ====
* '''Type:''' string
* '''Value:''' Name of the package that is the base package for this package. The base package must also be listed as a requirement for this package (cf. B_HPKG_ATTRIBUTE_ID_PACKAGE_REQUIRES). The package manager shall ensure that this package is installed in the same installation location as its base package.
* '''Allowed Values:''' Valid package names.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_FLAGS ("package:flags") ====
* '''Type:''' uint
* '''Value:''' Set of boolean flags applying to package.
* '''Allowed Values:''' Any combination of the following.
{| border=1 class="simple"
!1
!B_PACKAGE_FLAG_APPROVE_LICENSE
!this package's license requires approval (i.e. must be shown to and acknowledged by user before installation)
|-
!2
!B_PACKAGE_FLAG_SYSTEM_PACKAGE
!this is a system package (i.e. lives under /boot/system)
|}
* '''Default Value:''' 0.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_ARCHITECTURE ("package:architecture") ====
* '''Type:''' uint
* '''Value:''' System architecture this package was built for.
* '''Allowed Values:'''
{| border=1 class="simple"
!0
!B_PACKAGE_ARCHITECTURE_ANY
!this package doesn't depend on the system architecture
|-
!1
!B_PACKAGE_ARCHITECTURE_X86
!x86, 32-bit, built with gcc4
|-
!2
!B_PACKAGE_ARCHITECTURE_X86_GCC2
!x86, 32-bit, built with gcc2
|-
!3
!B_PACKAGE_ARCHITECTURE_SOURCE
!source code, doesn't depend on the system architecture
|-
!4
!B_PACKAGE_ARCHITECTURE_X86_64
!x86-64
|-
!5
!B_PACKAGE_ARCHITECTURE_PPC
!PowerPC
|-
!6
!B_PACKAGE_ARCHITECTURE_ARM
!ARM
|-
!7
!B_PACKAGE_ARCHITECTURE_M68K
!m68k
|}
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR ("package:version.major") ====
*'''Type:''' string
* '''Value:''' Major (first) part of package version.
* '''Allowed Values:''' Any single-lined string, composed of <alphanum_underline>
* '''Child Attributes:'''
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR: The minor part of the package version.
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO: The micro part of the package version.
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_PRE_RELEASE: The pre-release part of the package version.
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_REVISION: The revision part of the package version.
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR ("package:version.minor") ====
*'''Type:''' string
*'''Value:''' Minor (second) part of package version.
*'''Allowed Values:''' Any single-lined string, composed of <alphanum_underline>.
*'''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO ("package:version.micro") ====
* '''Type:''' string
* '''Value:''' Micro (third) part of package version.
* '''Allowed Values:''' Any single-lined string, composed of <alphanum_underline_dot>.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_PRE_RELEASE ("package:version.prerelease") ====
* '''Type:''' string
* '''Value:''' Pre-release (fourth) part of package version. Typically something like "alpha1", "beta2", "rc3".
* '''Allowed Values:''' Any single-lined string, composed of <alphanum_underline_dot>.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_REVISION ("package:version.revision") ====
* '''Type:''' uint
* '''Value:''' Revision (fifth) part of package version.
* '''Allowed Values:''' Any integer greater than 0.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_COPYRIGHT ("package:copyright") ====
* '''Type:''' string
* '''Value:''' Copyright applying to the software contained in this package.
* '''Allowed Values:''' Any (preferably single-lined) string.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_LICENSE ("package:license") ====
* '''Type:''' string
* '''Value:''' Name of license applying to the software contained in this package.
* '''Allowed Values:''' Any single-lined string.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_URL ("package:url") ====
* '''Type:''' string
* '''Value:''' URL of the packaged software's project home page.
* '''Allowed Values:''' A regular URL or an email-like named URL (e.g. "Project Foo <http://foo.example.com>").
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_SOURCE_URL ("package:source-url") ====
* '''Type:''' string
* '''Value:''' URL of the packaged software's source code or build instructions.
* '''Allowed Values:''' A regular URL or an email-like named URL (e.g. "Project Foo <http://foo.example.com>").
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES ("package:provides") ====
* '''Type:''' string
* '''Value:''' Name of a (optionally typed) entity that is being provided by this package.
* '''Allowed Values:''' Any string matching <entity_name_char>+.
* '''Child Attributes:''' none
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable version.
- B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES_COMPATIBLE: The major part of the resolvable compatible version.
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES_COMPATIBLE ("package:provides.compatible") ====
* '''Type:''' string
* '''Value:''' Major (first) part of the resolvable compatible version, structurally identical to B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR.
* '''Allowed Values:''' Any string matching <entity_name_char>+.
* '''Child Attributes:'''
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR: The minor part of the resolvable compatible version.
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO: The micro part of the resolvable compatible version.
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_PRE_RELEASE: The pre-release part of the resolvable compatible version.
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_REVISION: The revision part of the resolvable compatible version.
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_REQUIRES ("package:requires") ====
* '''Type:''' string
* '''Value:''' Name of an entity that is required by this package (and hopefully being provided by another).
* '''Allowed Values:''' Any string matching <entity_name_char>+.
* '''Child Attributes:'''
- B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator as int.
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable version.
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR ("package:resolvable.operator") ====
* '''Type:''' uint
* '''Value:''' Comparison operator for versions.
* '''Allowed Values:'''
{| border=1 class="simple"
!0
!B_PACKAGE_RESOLVABLE_OP_LESS
!less than the specified version
|}
{| border=1 class="simple"
!1
!B_PACKAGE_RESOLVABLE_OP_LESS_EQUAL
!less than or equal to the specified version
|}
{| border=1 class="simple"
!2
!B_PACKAGE_RESOLVABLE_OP_EQUAL
!equal to the specified version
|}
{| border=1 class="simple"
!3
!B_PACKAGE_RESOLVABLE_OP_NOT_EQUAL
!not equal to the specified version
|}
{| border=1 class="simple"
!4
!B_PACKAGE_RESOLVABLE_OP_GREATER_EQUAL
!greater than the specified version
|}
{| border=1 class="simple"
!5
!B_PACKAGE_RESOLVABLE_OP_GREATER
!greater than or equal to the specified version
|}
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_SUPPLEMENTS ("package:supplements") ====
* '''Type:''' string
* '''Value:''' Name of an entity that is supplemented by this package (i.e. this package will automatically be selected for installation if the supplemented resolvables are already installed).
* '''Allowed Values:''' Any string matching <entity_name_char>+.
* '''Child Attributes:'''
- B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator as int.
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable version.
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_CONFLICTS ("package:conflicts") ====
* '''Type:''' string
* '''Value:''' Name of an entity that this package conflicts with (i.e. only one of both can be installed at any time).
* '''Allowed Values:''' Any string matching <entity_name_char>+.
* '''Child Attributes:'''
- B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator as int.
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable version.
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_FRESHENS ("package:freshens") ====
* '''Type:''' string
* '''Value:''' Name of an entity that is being freshened by this package (i.e. this package will patch one or more files of the package that provide this resolvable).
* '''Allowed Values:''' Any string matching <entity_name_char>+.
* '''Child Attributes:'''
- B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator as int.
- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable version.
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_REPLACES ("package:replaces") ====
* '''Type:''' string
* '''Value:''' Name of an entity that is being replaced by this package (used if the name of a package changes, or if a package has been split).
* '''Allowed Values:''' Any string matching <entity_name_char>+.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_CHECKSUM ("package:checksum") ====
* '''Type:''' string
* '''Value:''' SHA256-chechsum of this package, in hexdump format. N.B.: this attribute can only be found in package repository files, not in package files.
* '''Allowed Values:''' 64-bytes of hexdump.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_GLOBAL_WRITABLE_FILE ("package:global-writable-file") ====
* '''Type:''' string
* '''Value:''' Relative path of a global writable file either included in the package or created by the included software. If the file is included in the package, it will be installed upon activation. In this case the attribute must contain a B_HPKG_ATTRIBUTE_ID_PACKAGE_WRITABLE_FILE_UPDATE_TYPE child attribute. The file may actually be a directory, which is indicated by the B_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY child attribute.
* '''Allowed Values:''' Installation location relative path (e.g. "settings/...").
* '''Child Attributes:'''
- B_HPKG_ATTRIBUTE_ID_PACKAGE_WRITABLE_FILE_UPDATE_TYPE: Specifies what to do with the writable file on package update.
- B_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY: Specifies whether the file is actually a directory.
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_SETTINGS_FILE ("package:user-settings-file") ====
* '''Type:''' string
* '''Value:''' Relative path of a user settings file created by the included software or required by the software to be created by the user. The file may actually be a directory, which is indicated by the B_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY child attribute.
* '''Allowed Values:''' Installation location relative path (i.e. "settings/...").
* '''Child Attributes:'''
- B_HPKG_ATTRIBUTE_ID_PACKAGE_SETTINGS_FILE_TEMPLATE: A template for the settings file.
- B_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY: Specifies whether the file is actually a directory.
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_WRITABLE_FILE_UPDATE_TYPE ("package:writable-file-update-type") ====
* '''Type:''' uint
* '''Value:''' Specifies what to do on package update when the writable file provided by the package has been changed by the user.
* '''Allowed Values:'''
{| border=1 class="simple"
!0
!B_WRITABLE_FILE_UPDATE_TYPE_KEEP_OLD
!the old file shall be kept
|}
{| border=1 class="simple"
!1
!B_WRITABLE_FILE_UPDATE_TYPE_MANUAL
!the old file needs to be updated manually
|}
{| border=1 class="simple"
!2
!B_WRITABLE_FILE_UPDATE_TYPE_AUTO_MERGE
!an automatic three-way merge shall be attempted
|}
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY ("package:is-writable-directory") ====
* '''Type:''' uint
* '''Value:''' Specifies whether the parent global writable file or user settings file attribute actually refers to a directory.
* '''Allowed Values:'''
{| border=1 class="simple"
!0
!The parent attribute refers to a file.
|}
{| border=1 class="simple"
!1
!The parent attribute refers to a directory.
|}
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_SETTINGS_FILE_TEMPLATE ("package:settings-file-template") ====
* '''Type:''' string
* '''Value:''' Relative path of an included template file for the user settings file.
* '''Allowed Values:''' Installation location relative path of a file included in the package.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_USER ("package:user") ====
* '''Type:''' string
* '''Value:''' Name of a user required by the package. Upon package activation the user will be created, if necessary.
* '''Allowed Values:''' Any valid user name, i.e. must be non-empty composed of <alphanum_underline>.
* '''Child Attributes:'''
- B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_REAL_NAME: The user's real name.
- B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_HOME: The user's home directory.
- B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_SHELL: The user's shell.
- B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_GROUP: The user's group(s).
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_REAL_NAME ("package:user.real-name") ====
* '''Type:''' string
* '''Value:''' The real name of the user.
* '''Allowed Values:''' Any string.
* '''Default Value:''' The user name.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_HOME ("package:user.home") ====
* '''Type:''' string
* '''Value:''' The path to the home directory of the user.
* '''Allowed Values:''' Any valid path.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_SHELL ("package:user.shell") ====
* '''Type:''' string
* '''Value:''' The path to the shell to be used for the user.
* '''Allowed Values:''' Any valid path.
* '''Default Value:''' "/bin/bash".
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_GROUP ("package:user.group") ====
* '''Type:''' string
* '''Value:''' A group the user belongs to. At least one must be specified.
* '''Allowed Values:''' Any valid group name, i.e. must be non-empty composed of <alphanum_underline>.
* '''Default Value:''' The default group for users.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_GROUP ("package:group") ====
* '''Type:''' string
* '''Value:''' Name of a group required by the package. Upon package activation the group will be created, if necessary.
* '''Allowed Values:''' Any valid group name, i.e. must be non-empty composed of <alphanum_underline>.
* '''Child Attributes:''' none
==== B_HPKG_ATTRIBUTE_ID_PACKAGE_POST_INSTALL_SCRIPT ("package:post-install-script") ====
* '''Type:''' string
* '''Value:''' Relative path of a script that shall be executed after package activation.
* '''Allowed Values:''' Installation location relative path of a file included in the package.
* '''Child Attributes:''' none
=== Haiku Package Repository Format ===
Very similar to the package format, there's a Haiku Package Repository (HPKR) file format. Such a file contains informative attributes about the package repository and package attributes for all packages contained in the repository. However, this format does not contain any files.
Two stacked format layers can be identified:
- A generic container format for structured data.
- A package format, extending the archive format with attributes for package management.
==== The Data Container Format ====
A HPKR file consists of three sections:
Header::
Identifies the file as HPKR file and provides access to the other sections.
Heap::
Contains the next two sections.
Repository Info::
A section containing an archived BMessage of a BRepositoryInfo object.
Package Attributes::
A section just like the package attributes section of the HPKG, only that this section contains the package attributes of all the packages contained in the repository (not just one).
The Repository Info and Package Attributes sections aren't really separate sections, as they are stored at the end of the heap.
==== Header ====
The header has the following structure:
<pre>
struct hpkg_repo_header {
uint32 magic;
uint16 header_size;
uint16 version;
uint64 total_size;
uint16 minor_version;
// heap
uint16 heap_compression;
uint32 heap_chunk_size;
uint64 heap_size_compressed;
uint64 heap_size_uncompressed;
// repository info section
uint32 info_length;
uint32 reserved1;
// package attributes section
uint64 packages_length;
uint64 packages_strings_length;
uint64 packages_strings_count;
};
</pre>
magic::
The string 'hpkr' (B_HPKG_REPO_MAGIC).
header_size::
The size of the header. This is also the absolute offset of the heap.
version::
The version of the HPKR format the file conforms to. The current version is
2 (B_HPKG_REPO_VERSION).
total_size::
The total file size.
minor_version::
The minor version of the HPKR format the file conforms to. The current minor version is
0 (B_HPKG_REPO_MINOR_VERSION). Additions of new attributes to the attributes section should
generally only increment the minor version. When a file with a greater minor version is
encountered, the reader should ignore unknown attributes.
heap_compression::
Compression format used for the heap.
heap_chunk_size::
The size of the chunks the uncompressed heap data are divided into.
heap_size_compressed::
The compressed size of the heap. This includes all administrative data (the chunk size array).
heap_size_uncompressed::
The uncompressed size of the heap. This is only the size of the raw data (including the repository info
and attributes section), not including administrative data (the chunk size array).
info_length::
The uncompressed size of the repository info section.
reserved1::
Reserved for later use.
packages_length::
The uncompressed size of the package attributes section.
packages_strings_length::
The size of the strings subsection of the package attributes section.
packages_strings_count::
The number of entries in the strings subsection of the package attributes section.
==== Attribute IDs ====
The package repository format defines only the top-level attribute ID B_HPKG_ATTRIBUTE_ID_PACKAGE. An attribute with that ID represents a package. Its child attributes specify the various meta information for the package as defined in the [#AttributeIDs1 Package Format Attribute IDs] section.
==== B_HPKG_ATTRIBUTE_ID_PACKAGE ("package") ====
* '''Type:''' string
* '''Value:''' Name of the package. The value is duplicated by the B_HPKG_ATTRIBUTE_ID_PACKAGE_NAME child attribute.
* '''Allowed Values:''' Any string matching <entity_name_char>+, with <entity_name_char> being any character but '-', '/', '=', '!', '<', '>', or whitespace.
* '''Child Attributes:'''
- Any B_HPKG_ATTRIBUTE_ID_PACKAGE_* top level attribute defined in the [#AttributeIDs1 Package Format Attribute IDs] section.
docs/develop/packages/HybridBuilds.rst
+59
View File
@@ -0,0 +1,59 @@
=============
Hybrid Builds
=============
A hybrid build of Haiku used to be a regular Haiku built with gcc 2, also
including the versions of the system libraries built with gcc 4 (or vice versa),
so that programs built with either compiler could be run. Package management
extends that concept and makes it more modular. Since it assigns gcc 2 and gcc 4
different (packaging) architectures ("x86_gcc2" and "x86"), we can now speak of
a primary architecture -- the one the system has been built for -- and a
secondary architecture -- the one the additional set of system libraries has
been built for. This also fits fine with the x86_64+x86 hybrid option we might
see in the future.
Since the files for the secondary architecture will live in one or more separate
packages we gain some flexibility. E.g. one could start out with a non-hybrid
Haiku and install the packages for the secondary architecture later on, and
remove them when no longer needed. In theory there's nothing preventing us from
supporting multiple secondary architectures (e.g. x86_64+x86+x86_gcc2), though
that might get somewhat confusing in practice.
The following sections list the requirements for the hybrid concept and the
packages built for a secondary architecture.
General Requirements
====================
1. Secondary architecture libraries and add-ons must live in respective
"<secondary_arch>" subdirectory, where the runtime loader will only look when
loading a secondary architecture executable.
#. Secondary architecture development libraries and headers must live in
"<secondary_arch>" subdirectory, where only the secondary architecture
compiler will look for them.
#. Secondary architecture executables must live in a "<secondary_arch>"
subdirectory, which by default isn't in PATH. The executables can be
symlinked to the primary architecture "bin" directory, using a symlink name
that doesn't clash with the primary architecture executable's name (by
appending to the name the secondary architecture name, e.g. "grep-x86"). If
there isn't a corresponding package for the primary architecture, the
executables may also live directly in the "bin" directory.
#. Application directories should live in a "<secondary_arch>" subdirectory,
unless there isn't a corresponding package for the primary architecture.
Secondary Architecture Package Requirements
===========================================
1. A secondary architecture package must not conflict with the corresponding
primary architecture package, so both can be active at the same time and in
the same installation location.
#. Packages that require a command ("cmd:...") and don't need it to be for a
particular architecture shouldn't need to be concerned with the
primary/secondary architecture issue. E.g. "cmd:grep" should provide them
with a working grep.
#. Secondary architecture packages providing a command should generally provide
both "cmd:<command>" and "cmd:<command>_<secondary_arch>"
(e.g. "cmd:grep" and "cmd:grep_x86_gcc2"). The former makes 2. possible. The
latter allows for packages to explicitly require the command for the
secondary architecture (3. of the general requirements actually implies that
provides item). The former should be omitted, when the behavior/output of the
command is architecture dependent (e.g. in case of compilers etc.).
#. Secondary architecture packages providing a library must provide
"lib:<library>_<secondary_arch>" (e.g. "lib:libncurses_x86").
docs/develop/packages/HybridBuilds.wiki
-24
View File
@@ -1,24 +0,0 @@
== Hybrid Builds ==
A hybrid build of Haiku used to be a regular Haiku built with gcc 2, also including the versions of the system libraries built with gcc 4 (or vice versa), so that programs built with either compiler could be run. Package management extends that concept and makes it more modular. Since it assigns gcc 2 and gcc 4 different (packaging) architectures ("x86_gcc2" and "x86"), we can now speak of a primary architecture -- the one the system has been built for -- and a secondary architecture -- the one the additional set of system libraries has been built for. This also fits fine with the x86_64+x86 hybrid option we might see in the future.
Since the files for the secondary architecture will live in one or more separate packages we gain some flexibility. E.g. one could start out with a non-hybrid Haiku and install the packages for the secondary architecture later on, and remove them when no longer needed. In theory there's nothing preventing us from supporting multiple secondary architectures (e.g. x86_64+x86+x86_gcc2), though that might get somewhat confusing in practice.
The following sections list the requirements for the hybrid concept and the packages built for a secondary architecture.
=== General Requirements ===
#Secondary architecture libraries and add-ons must live in respective "<secondary_arch>" subdirectory, where the runtime loader will only look when loading a secondary architecture executable.
2. Secondary architecture development libraries and headers must live in "<secondary_arch>" subdirectory, where only the secondary architecture compiler will look for them.
3. Secondary architecture executables must live in a "<secondary_arch>" subdirectory, which by default isn't in PATH. The executables can be symlinked to the primary architecture "bin" directory, using a symlink name that doesn't clash with the primary architecture executable's name (by appending to the name the secondary architecture name, e.g. "grep-x86"). If there isn't a corresponding package for the primary architecture, the executables may also live directly in the "bin" directory.
4. Application directories should live in a "<secondary_arch>" subdirectory, unless there isn't a corresponding package for the primary architecture.
=== Secondary Architecture Package Requirements ===
#A secondary architecture package must not conflict with the corresponding primary architecture package, so both can be active at the same time and in the same installation location.
2. Packages that require a command ("cmd:...") and don't need it to be for a particular architecture shouldn't need to be concerned with the primary/secondary architecture issue. E.g. "cmd:grep" should provide them with a working grep.
3. Secondary architecture packages providing a command should generally provide both "cmd:<command>" and "cmd:<command>_<secondary_arch>" (e.g. "cmd:grep" and "cmd:grep_x86_gcc2"). The former makes 2. possible. The latter allows for packages to explicitly require the command for the secondary architecture (3. of the general requirements actually implies that provides item). The former should be omitted, when the behavior/output of the command is architecture dependent (e.g. in case of compilers etc.).
4. Secondary architecture packages providing a library must provide "lib:<library>_<secondary_arch>" (e.g. "lib:libncurses_x86").
docs/develop/packages/Infrastructure.rst
+280
View File
@@ -0,0 +1,280 @@
=================================
Package Management Infrastructure
=================================
This pages gives an overview of what components belong to Haiku's package
management infrastructure and how they work and interact.
- **package** and **package_repo** are command line tools for building package
and package repository files. They are discussed in `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 dependencies
between packages.
- The **package management daemon** (short: package daemon) is a background
process that is activated whenever the user adds packages to or removes them
from one of their activation locations. It verifies that all dependencies are
fulfilled (prompting the user, if necessary) and performs whatever package
pre-activation/post-deactivation tasks are required. The daemon is also
contacted by the package manager (after it has resolved dependencies and
downloaded 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 command
line tool, and, ``HaikuDepot``, a GUI application.
.. _Building Packages: BuildingPackages.rst
.. image:: package-management-infrastructure.png
:align: center
Software Installation Locations
===============================
In Haiku there are two main locations where software is installed.
"/boot/system" and "/boot/home/config". "/boot/system" is where system-wide
software (i.e. software for all users), including the base system, is installed,
while "/boot/home/config" is only for the user's software. The discrimination
between those two doesn't make that much sense yet, but when Haiku supports
multi-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. Each
instance presents a virtually extracted union of the contents of all packages in
the subdirectory "packages" of that location. E.g. if one would extract the
contents of all package files in "/boot/system/packages" to an actual directory,
that would match exactly what is presented by packagefs in "/boot/system". With
a few exceptions -- packagefs provides several additional directories.
There are so-called shine-through directories which live on the underlying BFS
volume. Normally a file system mounted at a directory would completely hide
anything that is in that directory. These shine-through directories are handled
specially, though; packagefs shows them just like they are on the BFS volume.
One of those directories is "packages". This is necessary since otherwise it
wouldn't be possible to add, remove, or update any packages. Further
shine-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 respective
package file in a "packages" subdirectory of one of "/boot/system" or
"/boot/home/config". The package daemon, a background process that sleeps most
of the time, monitors the directory and, when happy with the newly added
package, it asks packagefs to presents its contents on the fly in the directory
structure. The package is said to be activated. Removing a package has the
opposite effect.
Things are a bit more complicated due to the fact that packages usually have
dependencies. 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 to
activate 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 are
fulfilled and whether there are any conflicts. If they aren't any problems, it
tells packagefs to activate/deactivate the packages as requested. In case there
are issues with the dependencies, according to how it has been configured via
settings, the daemon prompts the user immediately, checks remote repositories
for solutions to the problem and presents the user with the possible options, or
it even performs all necessary actions without bothering the user, if possible.
In the end, if the problems could be solved (e.g. by downloading additional
packages), the respective packages will be de-/activated, or, otherwise, nothing
will be changed.
To avoid always having to check all dependencies when booting, the package
daemon 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 is
missing or packages it refers to cannot be found or loaded, packagefs falls back
to activating all packages in the "packages" directory. The package daemon, once
started, checks the state.
Installation via Package Manager
--------------------------------
While manual software installation is possible, the more comfortable way is to
use the package manager. The package manager has a configurable list of remote
software repositories. It knows what software is available in those repositories
and what is installed locally. After the user has selected software packages to
be installed/deinstalled, package dependencies are resolved, and packages are
downloaded 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 then
contacts the package management daemon (via the package kit) to perform the
package activation changes. The daemon moves the new packages to the "packages"
directory, moves obsolete packages to an old state directory (also a
subdirectory in the "packages/administrative" directory, with the current
date and time encoded in its name) and asks packagefs to activate/deactivate the
respective packages. The old state directories allow recovery of old states.
That is particularly interesting for the system installation location. As as
safe mode/recovery option, the boot loader offers the user to select an old
installation 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 application
bundles. An application bundle is a fully self-contained package that doesn't
need to be installed anywhere. The implementation details have not yet been
decided on. The basic idea is to either mount a dedicated packagefs with the
content of such a package or have a special location where one of the three
already mounted packagefs instances (likely the "/boot/home/config" one) shows
that content. With a bit of Tracker (or even libbe) integration that will allow
the mounted directory to be opened or the application to be started when such a
package file has been double-clicked.
Installation Location Order and Consistency
-------------------------------------------
Having two separate installation locations for software requires some
considerations regarding their consistency and interactions. There's a
well-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 to
install a new/different version of a program in "/boot/home/config" and have it
override the version in "/boot/system".
This order also needs to be the order in which package dependencies are
directed. While it shall be possible to have a library in "/boot/home/config"
override one in "/boot/system" and have programs installed in the latter
location use the overriding library, packages in an installation location must
not have dependencies that can only be resolved to packages installed in a
location 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 would
work for one user, but not for another one who hasn't installed the library.
Consequently "/boot/system" is fully self-contained. All dependencies must be
resolved within it. A safe-mode boot should be possible with only the
"/boot/system" packagefs being mounted. As a consequence these constraints have
to be respected when software is installed or uninstalled.
Another challenge that comes with having two installation locations is that some
packages have compiled-in absolute paths to their own files (e.g. data files) or
to their dependencies. The former could be solved by building two different
versions of a package, but that wouldn't work with the latter and would be
tedious anyway. The solution are dynamically generated symbolic links in a fixed
location, "/boot/system/package-links" (symlinked to "/packages"), that for each
installed package and its dependencies refer to the respective installation
location.
For each installed package a subdirectory named like the package (package name
plus version) will be generated automatically. That subdirectory contains a
symlink ".self" which refers to the installation location of the package itself
as well as a symlink for each of its dependencies pointing to their installation
locations. Furthermore there's a symlink ".settings" which points to the
installation location's directory for global settings. E.g. for an OpenSSH
package 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/global
haiku -> ../..
lib:libssl -> ../..
Installing a different, compatible version of OpenSSL in "/boot/home/config"
would automatically change the respective dependency symlink. Once supporting
multi-user fully, the symlinks targets would also depend on the user ID of the
process that checks them, so software installed only for the user is handled
correctly.
While it depends on the location the package has been installed in where the
paths refer to, the absolute paths of the package links themselves remain
stable. So they can be compiled in, when a package is built, and will work
regardless of where the package is installed.
Another problem the package links can solve are incompatible versions of the
same package being installed in different locations. E.g. when a program and
another program it depends on are installed in "/boot/system", installing an
incompatible version of the latter in "/boot/home/config" will not break the
former, since the dependency link will continue to point to the compatible
version. With a bit of help from the runtime loader the same would work for
libraries. In practice that's less of a problem, though, since libraries usually
have a naming scheme and matching shared object names that already prevent
mismatches.
Software Repositories
=====================
A software repository is a collection of packages, usually accessible via the
internet. Haiku's package management solution allows to refer to any number of
software repositories from which packages can be downloaded and installed. The
structure of the respository is very simple. It's just a set of files which can
be downloaded via a common protocol (HTTP or FTP). One file is the repository
index file in `HPKR format`_. It lists all packages that are available in the
repository together with their descriptions and dependency information. It is
downloaded and cached, allowing user interfaces to show the information and the
dependency solver to do the computation locally. The other files are the
individual package files.
.. _HPKR format: FileFormat.rst#haiku-package-repository-format
Standard Repositories
---------------------
There are two standard repositories for Haiku:
- the Haiku repository, which only contains the small set of packages that is
built by Haiku's build system (haiku.hpkg, haiku_devel.hpkg, etc.) and
- the HaikuPorts repository, which contains the packages maintained by
HaikuPorts.
For the different builds and releases there are different instances of those two
repositories:
- There are snapshot repository instances for any repository version that was
ever available (to save space old versions may be removed/thinned out). Those
repositories will never be updated. Their main purpose is to be able to
retrospectively get a certain Haiku version for testing and comparisons.
- For each official major release there will be an instance of the two
repositories. For small updates the repositories will simply be updated. An
official Haiku release is pre-configured with the corresponding repositories,
so that the user can conveniently keep their Haiku up-to-date. The update to
the next major release has to be requested explicitly.
- Similar to the nightly images there are repository instances that are
continuously updated to the latest head of development. Those are suitable
mainly for testers and developers.
- For each state of the HaikuPorts repository a Haiku development revision
refers to a snapshot version of the repository is created. This allows to
check out and build older Haiku revisions with their corresponding HaikuPorts
packages.
The repositories are maintained via files in the Haiku git repository. For each
architecture and each repository the Haiku git repository contains a file
listing the packages for that repository. For the HaikuPorts repositories the
packages are listed with the respective version. For the Haiku repositories the
version is implied.
Whenever a developer wants to update or add a HaikuPorts package, the new
package file has to be uploaded to their git.haiku-os.org account and the
package list file for the repository has to be adjusted accordingly.
``jam upload-packages <packages-list>`` can be used in order to upload the
package(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 the
change, move the new package file(s) from the developer's account to the
repository directory, and build a new repository snapshot. If a package file is
missing or broken, the push will be rejected with a message notifying the
developer about the problem.
The creation and update of repositories for official releases has to be
triggered explicitly on the server. In either case the Haiku repository is built
by 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. the
package short and long description -- that are presented to the user. Therefore
translations for these strings must be available. Since it is impractical to
include the translations in the package and repository index files, they must be
provided in separate files. How exactly has not been decided on yet.
docs/develop/packages/Infrastructure.wiki
-106
View File
@@ -1,106 +0,0 @@
== Package Management Infrastructure ==
This pages gives an overview of what components belong to Haiku's package management infrastructure and how they work and interact.
*'''package''' and '''package_repo''' are command line tools for building package and package repository files. They are discussed in [[PackageManagement/BuildingPackages| 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 dependencies between packages.
*The '''package management daemon''' (short: package daemon) is a background process that is activated whenever the user adds packages to or removes them from one of their activation locations. It verifies that all dependencies are fulfilled (prompting the user, if necessary) and performs whatever package pre-activation/post-deactivation tasks are required. The daemon is also contacted by the package manager (after it has resolved dependencies and downloaded 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, <tt>pkgman</tt>, a command line tool, and, <tt>HaikuDepot</tt>, a GUI application.
[[Image(package-management-infrastructure.png, align=center)]]
=== Software Installation Locations ===
In Haiku there are two main locations where software is installed. "/boot/system" and "/boot/home/config". "/boot/system" is where system-wide software (i.e. software for all users), including the base system, is installed, while "/boot/home/config" is only for the user's software. The discrimination between those two doesn't make that much sense yet, but when Haiku supports multi-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. Each instance presents a virtually extracted union of the contents of all packages in the subdirectory "packages" of that location. E.g. if one would extract the contents of all package files in "/boot/system/packages" to an actual directory, that would match exactly what is presented by packagefs in "/boot/system". With a few exceptions -- packagefs provides several additional directories.
There are so-called shine-through directories which live on the underlying BFS volume. Normally a file system mounted at a directory would completely hide anything that is in that directory. These shine-through directories are handled specially, though; packagefs shows them just like they are on the BFS volume. One of those directories is "packages". This is necessary since otherwise it wouldn't be possible to add, remove, or update any packages. Further shine-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 respective package file in a "packages" subdirectory of one of "/boot/system" or "/boot/home/config". The package daemon, a background process that sleeps most of the time, monitors the directory and, when happy with the newly added package, it asks packagefs to presents its contents on the fly in the directory structure. The package is said to be activated. Removing a package has the opposite effect.
Things are a bit more complicated due to the fact that packages usually have dependencies. 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 to activate 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 are fulfilled and whether there are any conflicts. If they aren't any problems, it tells packagefs to activate/deactivate the packages as requested. In case there are issues with the dependencies, according to how it has been configured via settings, the daemon prompts the user immediately, checks remote repositories for solutions to the problem and presents the user with the possible options, or it even performs all necessary actions without bothering the user, if possible. In the end, if the problems could be solved (e.g. by downloading additional packages), the respective packages will be de-/activated, or, otherwise, nothing will be changed.
To avoid always having to check all dependencies when booting, the package daemon 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 is missing or packages it refers to cannot be found or loaded, packagefs falls back to activating all packages in the "packages" directory. The package daemon, once started, checks the state.
==== Installation via Package Manager ====
While manual software installation is possible, the more comfortable way is to use the package manager. The package manager has a configurable list of remote software repositories. It knows what software is available in those repositories and what is installed locally. After the user has selected software packages to be installed/deinstalled, package dependencies are resolved, and packages are downloaded 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 then contacts the package management daemon (via the package kit) to perform the package activation changes. The daemon moves the new packages to the "packages" directory, moves obsolete packages to an old state directory (also a subdirectory in the "packages/administrative" directory, with the current date and time encoded in its name) and asks packagefs to activate/deactivate the respective packages. The old state directories allow recovery of old states. That is particularly interesting for the system installation location. As as safe mode/recovery option, the boot loader offers the user to select an old installation 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 application bundles. An application bundle is a fully self-contained package that doesn't need to be installed anywhere. The implementation details have not yet been decided on. The basic idea is to either mount a dedicated packagefs with the content of such a package or have a special location where one of the three already mounted packagefs instances (likely the "/boot/home/config" one) shows that content. With a bit of Tracker (or even libbe) integration that will allow the mounted directory to be opened or the application to be started when such a package file has been double-clicked.
==== Installation Location Order and Consistency ====
Having two separate installation locations for software requires some considerations regarding their consistency and interactions. There's a well-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 <tt>PATH</tt>, <tt>LIBRARY_PATH</tt>, and <tt>ADDON_PATH</tt>). That e.g. allows a user to install a new/different version of a program in "/boot/home/config" and have it override the version in "/boot/system".
This order also needs to be the order in which package dependencies are directed. While it shall be possible to have a library in "/boot/home/config" override one in "/boot/system" and have programs installed in the latter location use the overriding library, packages in an installation location must not have dependencies that can only be resolved to packages installed in a location 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 would work for one user, but not for another one who hasn't installed the library. Consequently "/boot/system" is fully self-contained. All dependencies must be resolved within it. A safe-mode boot should be possible with only the "/boot/system" packagefs being mounted. As a consequence these constraints have to be respected when software is installed or uninstalled.
Another challenge that comes with having two installation locations is that some packages have compiled-in absolute paths to their own files (e.g. data files) or to their dependencies. The former could be solved by building two different versions of a package, but that wouldn't work with the latter and would be tedious anyway. The solution are dynamically generated symbolic links in a fixed location, "/boot/system/package-links" (symlinked to "/packages"), that for each installed package and its dependencies refer to the respective installation location.
For each installed package a subdirectory named like the package (package name plus version) will be generated automatically. That subdirectory contains a symlink ".self" which refers to the installation location of the package itself as well as a symlink for each of its dependencies pointing to their installation locations. Furthermore there's a symlink ".settings" which points to the installation location's directory for global settings. E.g. for an OpenSSH package installed in "/boot/home/config" and OpenSSL installed in "/boot/system" the directory could look like this:
<pre>
/boot/system/package-links/openssh-5.8p2-1/
.self -> ../../../home/config
.settings -> ../../../home/config/settings/global
haiku -> ../..
lib:libssl -> ../..
</pre>
Installing a different, compatible version of OpenSSL in "/boot/home/config" would automatically change the respective dependency symlink. Once supporting multi-user fully, the symlinks targets would also depend on the user ID of the process that checks them, so software installed only for the user is handled correctly.
While it depends on the location the package has been installed in where the paths refer to, the absolute paths of the package links themselves remain stable. So they can be compiled in, when a package is built, and will work regardless of where the package is installed.
Another problem the package links can solve are incompatible versions of the same package being installed in different locations. E.g. when a program and another program it depends on are installed in "/boot/system", installing an incompatible version of the latter in "/boot/home/config" will not break the former, since the dependency link will continue to point to the compatible version. With a bit of help from the runtime loader the same would work for libraries. In practice that's less of a problem, though, since libraries usually have a naming scheme and matching shared object names that already prevent mismatches.
=== Software Repositories ===
A software repository is a collection of packages, usually accessible via the internet. Haiku's package management solution allows to refer to any number of software repositories from which packages can be downloaded and installed. The structure of the respository is very simple. It's just a set of files which can be downloaded via a common protocol (HTTP or FTP). One file is the repository index file in [[PackageManagement/FileFormat#HaikuPackageRepositoryFormat| HPKR format]]. It lists all packages that are available in the repository together with their descriptions and dependency information. It is downloaded and cached, allowing user interfaces to show the information and the dependency solver to do the computation locally. The other files are the individual package files.
==== Standard Repositories ====
There are two standard repositories for Haiku:
*the Haiku repository, which only contains the small set of packages that is built by Haiku's build system (haiku.hpkg, haiku_devel.hpkg, etc.) and
*the HaikuPorts repository, which contains the packages maintained by HaikuPorts.
For the different builds and releases there are different instances of those two repositories:
*There are snapshot repository instances for any repository version that was ever available (to save space old versions may be removed/thinned out). Those repositories will never be updated. Their main purpose is to be able to retrospectively get a certain Haiku version for testing and comparisons.
*For each official major release there will be an instance of the two repositories. For small updates the repositories will simply be updated. An official Haiku release is pre-configured with the corresponding repositories, so that the user can conveniently keep their Haiku up-to-date. The update to the next major release has to be requested explicitly.
*Similar to the nightly images there are repository instances that are continuously updated to the latest head of development. Those are suitable mainly for testers and developers.
*For each state of the HaikuPorts repository a Haiku development revision refers to a snapshot version of the repository is created. This allows to check out and build older Haiku revisions with their corresponding HaikuPorts packages.
The repositories are maintained via files in the Haiku git repository. For each architecture and each repository the Haiku git repository contains a file listing the packages for that repository. For the HaikuPorts repositories the packages are listed with the respective version. For the Haiku repositories the version is implied.
Whenever a developer wants to update or add a HaikuPorts package, the new package file has to be uploaded to their git.haiku-os.org account and the package list file for the repository has to be adjusted accordingly. <tt>jam upload-packages <packages-list></tt> can be used in order to upload the package(s) or the packages could just be <tt>scp</tt>'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 the change, move the new package file(s) from the developer's account to the repository directory, and build a new repository snapshot. If a package file is missing or broken, the push will be rejected with a message notifying the developer about the problem.
The creation and update of repositories for official releases has to be triggered explicitly on the server. In either case the Haiku repository is built by 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. the package short and long description -- that are presented to the user. Therefore translations for these strings must be available. Since it is impractical to include the translations in the package and repository index files, they must be provided in separate files. How exactly has not been decided on yet.
docs/develop/packages/Migration.rst
+201
View File
@@ -0,0 +1,201 @@
===============================
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" or "/boot/home/config".
- The directory layout has changed and many directories have become read-only.
Cf. `DirectoryStructure`_ for details.
.. _DirectoryStructure: DirectoryStructure.rst
- 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.
- Haiku's stage 1 boot loader (the boot block in the BFS partition) has changed.
That means a Haiku partition made bootable from an old Haiku -- or more
generally: with a ``makebootable`` that predates package management -- will
not be able to boot a package management Haiku. You will have to run the new
``makebootable`` to make it bootable again. The new ``makebootable`` may or
may not run on an old Haiku. The safest way is to do that from a running
package management Haiku (e.g. booted off a USB stick or CD).
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 "<arch>" 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 (by default) live in "/boot/system/bin/<arch>". 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. Executing the new
command ``setarch <arch>`` will start a new shell with a respectively modified
``PATH``. The commands of the secondary tool chain are also available in the
standard path with a name suffixed with "-<arch>" (e.g. "gcc-x86" for the
gcc 4 executable on a gcc2/gcc4 hybrid).
- Software can be packaged using the ``package`` tool. Cf. `BuildingPackages`_
for more information.
.. _BuildingPackages: BuildingPackages.rst
- The ``find_directory()`` API has been partially deprecated. While there are
still some use cases where it should be used, in many cases the new
``find_path*()`` API, respectively the ``BPathFinder`` class should be used
instead (cf. the `API documentation`_).
.. _API documentation: https://www.haiku-os.org/docs/api/FindDirectory_8h.html
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.
For example, for building the default configuration of Haiku from a file
system with proper xattr support, your configure options could look like
this::
$ ./configure --build-cross-tools x86_gcc2 ../buildtools --build-cross-tools x86 --use-xattr
- 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_<arch>.hpkg", "haiku_<arch>_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 "_<arch>" suffix (e.g.
TARGET_GCC_<arch>, TARGET_DEFINES_<arch>, 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. `src/kits/textencoding/Jamfile`_ for a small
example.
.. _src/kits/textencoding/Jamfile:
https://github.com/haiku/haiku/blob/master/src/kits/textencoding/Jamfile
- 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.
`src/add-ons/mail_daemon/inbound_protocols/pop3/Jamfile`_ for an example.
.. _src/add-ons/mail_daemon/inbound_protocols/pop3/Jamfile:
https://github.com/haiku/haiku/blob/master/src/add-ons/mail_daemon/
inbound_protocols/pop3/Jamfile
- 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,
empties "/boot/system/packages" in the image, and copies the updated packages
there. It's a poor man's system update. Packages you have installed manually
will be removed. The old "update-all" build profile action still exits. It has
the effect of "update-packages" and additionally replaces all other files that
are usually copied to the image.
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
`haikuporter documentation`_ for more information.
.. _haikuporter documentation:
https://github.com/haikuports/haikuports/wiki/HaikuPorterForPM
docs/develop/packages/Migration.wiki
-52
View File
@@ -1,52 +0,0 @@
== 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 <tt>pkgman</tt> -- <tt>pkgman search/install/uninstall/update ...</tt> 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" or "/boot/home/config".
*The directory layout has changed and many directories have become read-only. Cf. [[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.
*Haiku's stage 1 boot loader (the boot block in the BFS partition) has changed. That means a Haiku partition made bootable from an old Haiku -- or more generally: with a <tt>makebootable</tt> that predates package management -- will not be able to boot a package management Haiku. You will have to run the new <tt>makebootable</tt> to make it bootable again. The new <tt>makebootable</tt> may or may not run on an old Haiku. The safest way is to do that from a running package management Haiku (e.g. booted off a USB stick or CD).
=== 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 "<arch>" subdirectory of their usual location. This doesn't hold for the system headers which exist only in the primary location.
*<tt>setgcc</tt> is gone. The commands of the tool chain for the secondary architecture (by default) live in "/boot/system/bin/<arch>". Prepending that path to the <tt>PATH</tt> environment variable would make them shadow the respective primary architecture commands -- the effect would be similar to the one <tt>setgcc</tt> had, but only for the current shell session. Executing the new command <tt>setarch <arch></tt> will start a new shell with a respectively modified <tt>PATH</tt>. The commands of the secondary tool chain are also available in the standard path with a name suffixed with "-<arch>" (e.g. "gcc-x86" for the gcc 4 executable on a gcc2/gcc4 hybrid).
*Software can be packaged using the <tt>package</tt> tool. Cf. [[PackageManagement/BuildingPackages| BuildingPackages]] for more information.
*The <tt>find_directory()</tt> API has been partially deprecated. While there are still some use cases where it should be used, in many cases the new <tt>find_path*()</tt> API, respectively the <tt>BPathFinder</tt> class should be used instead (cf. the [http://api.haiku-os.org/FindDirectory_8h.html API documentation]).
=== 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 <tt>configure</tt> script option have changed:
**<tt>--build-cross-tools</tt> and <tt>--build-cross-tools-gcc4</tt> have been merged. The (packaging) architecture must always be specified.
**<tt>--build-cross-tools</tt> and <tt>--cross-tools-prefix</tt> can be given multiple times to specify hybrid builds. Only for the first <tt>--build-cross-tools</tt> the path to the build tools must be given.
For example, for building the default configuration of Haiku from a file system with proper xattr support, your configure options could look like this:<br>
<tt>$ ./configure --build-cross-tools x86_gcc2 ../buildtools --build-cross-tools x86 --use-xattr</tt>
**The new option <tt>--target-arch</tt> has been introduced for use on Haiku for builds with the native compiler. By default, if neither <tt>--build-cross-tools</tt> nor <tt>--cross-tools-prefix</tt> 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). <tt>--target-arch</tt> 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 <tt>--use-xattr-ref</tt> can be used when extended attributes are available, but their size limit prevents use of <tt>--use-xattr</tt> (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 <tt>--use-32bit</tt> 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_<arch>.hpkg", "haiku_<arch>_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 "_<arch>" suffix (e.g. TARGET_GCC_<arch>, TARGET_DEFINES_<arch>, 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 <tt>jam -q @alpha-raw update libbe.so</tt> will first update libbe.so in the haiku.hpkg package and then update haiku.hpkg in the image. A <tt>jam -q @alpha-raw update haiku.hpkg</tt> 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 <tt>jam -q haiku.hpkg</tt>. 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, empties "/boot/system/packages" in the image, and copies the updated packages there. It's a poor man's system update. Packages you have installed manually will be removed. The old "update-all" build profile action still exits. It has the effect of "update-packages" and additionally replaces all other files that are usually copied to the image.
=== 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 [https://github.com/haikuports/haikuports/wiki/HaikuPorterForPM haikuporter documentation] for more information.
docs/develop/packages/OldIdeas.rst
+498
View File
@@ -0,0 +1,498 @@
========================
Package Management Ideas
========================
.. contents::
:depth: 2
:backlinks: none
This page is a place to hash out ideas regarding Haiku's package management
(and creation). The following is a draft specification for the package
management system to be included in R1. It is based on (1), (2) and the
discussion in (5). The draft does not yet cover everything from (1), however.
Requirements
============
This section describes the intended user experience.
HaikuBits
---------
HaikuBits is a complete directory of software for the Haiku platform. It is the
one place a user needs when looking for Haiku software. While it does not host
all software binaries, it does list 99.9% of all software available for Haiku.
Software is classified into a number of categories. For each software, HaikuBits
provides a short description, one or more screenshots, a link to the author's
homepage and a download link. Additionally, a software's page has a community
rating and important information such as security notices.
Bundles
-------
A bundle_ is a single file that contains the binaries, data files and
documentation. This makes software self-contained and easy to handle. An
application can be run by double-clicking the bundle icon. Obvious exceptions
to this rule are drivers and libraries. These have to be installed to be of any
use. The contents of a bundle can be inspected by opening the bundle by means of
a context-menu option which opens the bundle in Tracker just like a directory.
.. _bundle: http://en.wikipedia.org/wiki/Application_Bundle
Optionally, an **application** bundle can be **installed** by moving it to
``/boot/apps`` (system-wide) or in ``/boot/home/<user>/apps`` (user-local).
Another option is to right-click the icon and select "install for everyone"
(only admins) or "install only for me". Any initial configuration (accepting a
license) can be performed the first time a bundle is being run.
**Libaries** can be installed the same way. The user normally does not have to
install libraries manually, as the package manager will do so when it is needed,
asking the user for permission.
When an application bundle has been installed, shortcuts to the application
appear in the Deskbar menu. This menu is subdivided into a number of a
predefined categories (games, graphics, internet, ...) that match those on
HaikuBits.
**Drivers** ... ?
**brecht**: I don't like Waldemar's idea of having bundles spread all around
the filesystem, hence the clear distinction between installed and
non-installed bundles. This might be a necessity for multi-user too.
**axeld**: I have to agree with brecht. And also, I like the package file
system best, as it also solves on how to deal with ported software, and
libraries as well. Only drivers would probably need special treatment
(depends on how early the package file system is available, but I guess that
could be made work as well, like having a "actually install on disk" option
for driver packages).
**wkornewald**: My original intention was to not force the user through any
installation procedure. Simply download the app and run it directly from the
downloads folder to see if it works well and if yes the user can move it to
the "Apps" folder.
Management
----------
**Uninstallation** is performed by simply removing the bundle from
``/boot/apps`` or ``/boot/home/<user>/apps``.
A user's application **settings** are kept when a bundle is uninstalled or
deleted. The system however provides a comprehensive listing of applications for
which user settings exist. The user can choose to delete settings for each of
the bundles.
Application folders (``/boot/apps`` and ``/boot/home/<user>/apps``) display the
list of installed bundles including information (description, availability of
updates, security risk warning), just like the mail folder in BeOS displays
emails.
**wkornewald**: The system should automatically remove settings of deleted
apps after a certain amount of time. You don't really want the user to
manually clean up his system. The cleanup delay should be long enough to allow
the user to update an app by deleting the old version and downloading the new
version and it should be long enough to allow the user to "undo" his action.
Maybe 1-2 months is fine.
**pulkomandy**: Deleting files without asking doesn't look right to me. Either
delete them as soon as the app is removed, or keep them forever. I like
Debian/apt way of doing it : when you delete a package, it's listed in the
package manager as 'removed, residual config files' and you can remove these
from there.
Dependencies
------------
The user does not have to worry about dependencies. If a bundle depends on other
bundles, the package manager should make sure they are fulfilled (on run). If a
dependency is not fulfilled, the system will ask the user for confirmation and
automatically install any required bundles. This requires an internet
connection.
Alternatively, a user can download a **fat bundle** that includes the
dependencies as well.
Updates
-------
All *installed software* can be checked for new versions. For each of the
installed applications, the changes with respect to the installed version can be
displayed. Updates are flagged as 'strongly recommended' when security problems
are known. The user can select which applications he/she would like to update
and have the system perform the updates.
By default, the updater tool does not show libraries in order to keep the list
of updates as short as possible and understandable by the non-technical user.
Libaries should only be updated when there are known problems with them.
Implementation
==============
In this section the implementation of the system is discussed.
Bundles
-------
A bundle is a compressed disk image that contains:
- application executable(s) & data
- metadata
- name
- version
- (revision?)
- hash (integrity-check)
- author
- homepage
- license
- category (for grouping applications in the Deskbar menu)
- shortcuts to appear in the Deskbar menu
- a default shortcut to run when the bundle is being "run"
- right-clicking bundle could offer the option of opening a help document
about the application
There are a number of different bundle types:
- application
- library
- driver
- font
- ...
Library, driver and font bundles have to be installed.
Install or not?
---------------
As bundles have to be compressed for distribution, they will need to be
uncompressed at some point. There are two options:
- Before using a bundle, it is decompressed. This is very similar to installing,
which many wanted to avoid.
- The bundle's contents are decompressed on access. This is less efficient as
decompression needs to be performed on each access, as opposed to only one
time during installation. Performance of large applications and heavy games in
particular will suffer.
It is possible to split application bundles into two sub-types; those that have
to be installed, and those that can be run as-is.
**brecht**: While I initially liked the idea of not having to install
software, I now feel that it is not suited for all types of applications and
games. While we can make a differentiate between 'large' and 'small'
applications and require installation of large apps (or suffer from poor
performance), this feels like a bit of a kludge. Is is really that bad to
'install' software once? Installing can be reduced to decompressing and should
not bother the user much. If the user knows he has to install **all** bundles,
there can be no confusion.
**wkornewald**: I don't fully remember my original proposal (it's been several
years :), but I think there's a middle-path: When the bundle is opened for the
first time it's decompressed and cached automatically. When the bundle is
deleted from the file system the cache is cleaned, too. That way you have the
best of both worlds and the user only has a slow first start, but all
subsequent app starts will be fast. Maybe the cache itself could be a single
uncompressed bundle/image file if that's more efficient than having lots of
small files spread over the main file system. A large coherent file can
probably be read into memory much faster and should speed up app starts
noticeably.
Merged
------
By means of a union pkgfs (3). All ports are mounted under ``/boot/common``.
It is not clear how multiple versions of libraries and applications can be
handled in this scheme.
Self-contained
--------------
By means of assignfs (4). Each port receives its own unique assign:
``/boot/apps/<port>-<version>-<revision>``
**axeld**: I think the best solution would be a unionfs approach: the package
file system would just blend in the packages where needed. User packages would
be merged with the contents of config/, while system wide ones would be merge
with the contents of /boot/common/.
Settings
--------
global settings/user settings
Multiple Application Version
````````````````````````````
how to handle
Dependency Hell
---------------
`Dependency hell`_ is a problem mostly for ports. That does not mean it can be
ignored. At least in the early years of Haiku, ports will be an important source
of software.
.. _Dependency hell: http://en.wikipedia.org/wiki/Dependency_hell
Avoiding
````````
Bundles are always fat bundles. All required libraries are included in the
bundle. Problem solved! However, this very area-inefficient. Nor is it a
realistic solution for bundles that depend on large packages like Python or
Perl.
Tacking
```````
In order to solve conflicting dependencies, it is necessary to be able to have
multiple versions of a library installed. Even worse, some libraries can be
built with different options.
To make this work, it is obvious that a central bundle repository is required:
HaikuBits. Alongside offering a browsable directory of software like BeBits, it
stores information about dependencies. Dependency information (problems arising
from certain combinations of bundles) is updated by the community.
An example. When ABC-1.0 is released, its dependency libfoo is at version
1.2.10. Bundle ABC-1.0 specifies "libfoo >= 1.2.10" as a dependency. Later, when
libfoo 1.2.12 is released, it appears that this breaks ABC-1.0. HaikuBits is
updated to indicate this: "libfoo >= 1.2.10 && != 1.2.12". When ABC-1.0 is now
downloaded from HaikuBits, the bundle contains the updated information. A
software updating tool can also check HaikuBits to see whether dependencies are
still OK.
Because the act of porting can introduce additional incompatibilities, each port
should be tagged with a revision number to uniquely identify it. Revisions can
also be used to differentiate between ports with different build options.
Specifying build options in the dependency information seems overkill anyway, as
we should strive to have as few port revisions as possible (developers should
have dependencies installed as bundles before porting).
The bundle metadata needs to be extended to include information about the
dependencies:
- minimum/maximum version
- preferred version/revision
- non-working versions/revisions
While bundles will not be available for download for retail software, it still
makes sense to record dependency information about it on HaikuBits.
Having an application use a particular library version can be done by
manipulating LD_LIBRARY_PATH or by virtually placing the library in the
applications directory by means of assignfs or pkgfs.
Note the important difference with typical Linux package management systems. In
Linux, the repository typically offers only one version of a particular package.
This is the result of keeping all packages in the repository in sync, in order
to avoid conflicting dependencies. In the proposed system however, the user is
free to install any version of a bundle, as there is no need for any global
synchronization of all bundles.
**axeld**: while having a central repository is a good thing, I don't think
our package manager should be based on that idea. I would allow each package
to define its own sources (the user can prevent that, of course). That way, we
avoid the situation of having to choose between outdated repositories, and
unstable software (or even having to build it on your own) like you usually
have to do in a Linux distribution. The central repository should also be a
fallback, though, and try to host most library packages.
Since we do care about binary compatibility, and stable APIs, having a central
repository is not necessary, or something desirable at all IMO.
**brecht**: I agree. I see the repository more as a central entity keeping
track of all software versions and the dependencies between them. This
dependency information is updated based on user feedback. I don't think it is
necessary to have the repository be the one and only source for bundles,
however. It can keep instead a list of available mirrors. However, it is
probably a good idea to have one large reliable mirror (hosting the most
important bundles) managed by Haiku Inc. alongside the repository in order not
to be too dependent on third parties.
libalpm
-------
(and it's tool: pacman)
libalpm is the package management library used on ArchLinux, most people know it
as "pacman" since that's the main tool to use, however, all the functionality is
part of the libalpm library which could be utilized to create a nice GUI
frontend for the package manager. It of course can also be adapted.
It uses libarchive to extract archives, and either libdownload or libfetch to
download files - although one can also have it use an external command, like
curl or wget.
The current status is this:
As far as libfetch is concerned: compiles and is linked to, but it doesn't
really work, so I'm using curl instead - it works like a charm.
The important part: libarchive needed some work to support zip files in a useful
way. Basically, it now supports seeking (which it didn't before), the
central-directory headers for ZIP files (so it supports stuff like symlinks),
and BeOS file attributes! Also, when reading from a source which doesn't allow
seeking (... which are... none - on our case) it simply reads the local headers,
but can also - if explicitly requested - provide "update"-entries to update the
raw data when the central directory is reached (but those are of no importance
anymore).
What's good about libalpm? Well, it provides useful configuring mechanisms, it
stores dependencies and can also give you a list of which packages require a
certain package. It keeps a database containing package information, including a
file list. Configuration files in packages can be listed as such, which causes
them to be installed as \*.pacnew when they are upgraded (unless the new and old
files equal - an md5 sum check is used there.) It provides the ability to use
different database directories which allows us to have an automated way of
creating package bundles. For instance, I can set the installdir to
/tmp/mypackage and install the game "einstein" including its dependencies there,
then move /tmp/mypackage/einstein/common/lib to /tmp/mypackage/einstein/lib,
remove the unnecessary manpages, share files (well, usually anything else which
is in the common/ folder), and then strip those dependencies from einstein's
.PKGINFO file and create a bundled package which I can then install normally to
say /boot/apps.
Another useful feature is the possibility to change the root directory. When a
package contains a .INSTALL script, libalpm chroot()s into the root directory,
cd()s into the installation directory, and then executes the .INSTALL script
(which means, that install-scripts can and should work relative to the
installation directory, although, if necessary, the absolute path is available
in $PWD)
Also, libalpm works similar to an actual database. It doesn't blindly attempt to
install a package, but first check for file conflicts, see if any files need
backups or configuration files need to be installed as .pacnew, and then
installs a package. If you install multiple packages at once, then it only
either installs all of them, or none. It allows you to find the owning package
of a file in the filesystem as well as listing all the files and dependencies of
a package.
Where does it get the packages from? Two possibilities: One can use package
files directly - which could be made in such a way that you could also just
unzip them. In fact, it might be useful to put the .PKGINFO into the zip file as
some extra data which is not unzipped when simply using ``unzip``, although
package creation is easier if it's just a file. The other one being
repositories. The pacman utility currently allows you to list repositories like
this in pacman.conf::
[core]
Server = file:///MyRepositories
[devel]
Server = file:///MyRepositories
[public]
Server = http://www.public-repository.com/
When you synchronize the repository databases, pacman downloads the file
<Server>/<Reponame>.db.tar.gz which contains a list of packages with
dependencies. When you install a package from such a repository, it downloads
them from the very same location: <Server>/<Package File> The repo.db.tar.gz
files are currently created using the tools ``repo-add`` and ``repo-remove``
provided in the pacman package. Those extract information from the .PKGINFO file
and put it into the database which can be used as a repository then.
Here's a little log of using pacman to install a package file, and bundle a
package with dependencies together into one package file.
http://stud4.tuwien.ac.at/~e0725517/using-pacman-on-haiku.log.txt
Pros
````
- It has been used on archlinux for a long time - so it works.
- It's obviously possibly to compile and use it on haiku
- Since most of its functionality is part of a library, it can be reused to
build a GUI-application utilizing libalpm
- pacman also provides scripts for building packages using a PKGBUILD script.
Cons
````
- Likely to cause unwanted restrictions in the package management system.
..
**brecht**: I don't have a detailed view of pacman yet, but as far as I can
see it is very similar to your average Linux package manager. As we want
software management to be fundamentally different from the way Linux
distributions handle it (because it simply is not a very elegant solution), I
don't think pacman is a good choice.
**Blub**: Let me clarify: I was not suggesting to use 'pacman' as a package
manager, I was just thinking that its library could be a useful codebase for a
package-database, to keep track of dependencies, available packages and
updates. It 'could' be used to unpack/install packages into a 'specified'
folder, like /boot/apps (and even install dependencies into the same folder if
wanted), or, it could just as well be used to simply keep track of where which
package has been installed to without worrying about the actual contents.
Although when stripping the code to unpack the archives and keeping track of
their files it is indeed better to create something new.
Brainstorming Results from BeGeistert
=====================================
These features were discussed/written down at BeGeistert:
- Integrated app to add packages
- Knows about repositories
- Defined protocol to add repositories that everyone can use (for example
through description files with a special MIME type)
- Multiple installations of the same package (if the software supports it)
- Maintain shared libraries
- runtime_loader uses package info to resolve libraries
- Install packages per user
- Repositories support keys to verify packages
- Package database of installed packages
- Packagemanagement API
- Binary diffing for packages
- Export/publish the set of installed packages to another system
- System updates
- Quality of packages (QA integrated into the process of releasing a package)
- Property of live update possible
Package Format
==============
A package format has to meet the following requirements:
- It must be able to store BeOS/Haiku file attributes.
- If the package shall be used directly (i.e. without prior extracting) by a
package file system, fast random access to the file data must be possible.
This disqualifies zipped TAR like formats.
[PackageFormat The Haiku Package format] specifies a format meeting these
requirements.
References
==========
\(1) http://www.haiku-os.org/glass_elevator/rfc/installer
\(2) http://www.freelists.org/post/haiku-development/software-management-proposal
\(3) http://www.freelists.org/post/haiku-development/software-organizationinstallation,8 and
http://www.freelists.org/post/haiku-development/software-organizationinstallation,55
**jonas.kirilla**: I hope it's clear enough in reference 3 (above) that my
ideas on package management approach it from a different angle. Which may or
may not overlap with the use of libalpm. FWIW, I'm not ready to endorse all
aspects of this proposal.
\(4) http://www.freelists.org/post/haiku-development/Pathrelocatable-software-and-assigns
\(5) http://www.freelists.org/post/haiku-development/software-organizationinstallation
Other package managers to steal ideas from:
- 0install_ - probably the most interesting
- klik_
- glick_
- Conary_
.. _0install: http://0install.net/injector-design.html
.. _klik: http://en.wikipedia.org/wiki/Klik_(packaging_method)
.. _glick: http://www.gnome.org/~alexl/glick/
.. _Conary: http://wiki.rpath.com/wiki/Conary
Useful articles:
- `OSNews: Decentralised Installation Systems`_ - article by the 0install author
- `Package management system`_
.. _OSNews\: Decentralised Installation Systems:
http://www.osnews.com/story/16956/Decentralised-Installation-Systems/
.. _Package management system:
http://en.wikipedia.org/wiki/Package_management_system
Misc.
- `Integrating OptionalPackages into Haiku's build system`_
.. _Integrating OptionalPackages into Haiku's build system:
http://lists.ports.haiku-files.org/pipermail/
haikuports-devs-ports.haiku-files.org/2009-June/000516.html
docs/develop/packages/OldIdeas.wiki
-287
View File
@@ -1,287 +0,0 @@
== Package Management Ideas ==
This page is a place to hash out ideas regarding Haiku's package management (and creation). The following is a draft specification for the package management system to be included in R1. It is based on (1), (2) and the discussion in (5). The draft does not yet cover everything from (1), however.
=== Requirements ===
This section describes the intended user experience.
==== HaikuBits ====
HaikuBits is a complete directory of software for the Haiku platform. It is the one place a user needs when looking for Haiku software. While it does not host all software binaries, it does list 99.9% of all software available for Haiku.
Software is classified into a number of categories. For each software, HaikuBits provides a short description, one or more screenshots, a link to the author's homepage and a download link. Additionally, a software's page has a community rating and important information such as security notices.
==== Bundles ====
A [http://en.wikipedia.org/wiki/Application_Bundle bundle] is a single file that contains the binaries, data files and documentation. This makes software self-contained and easy to handle. An application can be run by double-clicking the bundle icon. Obvious exceptions to this rule are drivers and libraries. These have to be installed to be of any use. The contents of a bundle can be inspected by opening the bundle by means of a context-menu option which opens the bundle in Tracker just like a directory.
Optionally, an '''application''' bundle can be '''installed''' by moving it to <tt>/boot/apps</tt> (system-wide) or in <tt>/boot/home/<user>/apps</tt> (user-local). Another option is to right-click the icon and select "install for everyone" (only admins) or "install only for me". Any initial configuration (accepting a license) can be performed the first time a bundle is being run.
'''Libaries''' can be installed the same way. The user normally does not have to install libraries manually, as the package manager will do so when it is needed, asking the user for permission.
When an application bundle has been installed, shortcuts to the application appear in the Deskbar menu. This menu is subdivided into a number of a predefined categories (games, graphics, internet, ...) that match those on HaikuBits.
'''Drivers''' ... ?
<pre>
#div style="background-color: #EEEEEE; border: 1px solid; margin: 20pt; padding: 5pt;"
'''brecht''': I don't like Waldemar's idea of having bundles spread all around the filesystem, hence the clear distinction between installed and non-installed bundles. This might be a necessity for multi-user too.
'''axeld''': I have to agree with brecht. And also, I like the package file system best, as it also solves on how to deal with ported software, and libraries as well. Only drivers would probably need special treatment (depends on how early the package file system is available, but I guess that could be made work as well, like having a "actually install on disk" option for driver packages).
'''wkornewald''': My original intention was to not force the user through any installation procedure. Simply download the app and run it directly from the downloads folder to see if it works well and if yes the user can move it to the "Apps" folder.
</pre>
==== Management ====
'''Uninstallation''' is performed by simply removing the bundle from <tt>/boot/apps</tt> or <tt>/boot/home/<user>/apps</tt>.
A user's application '''settings''' are kept when a bundle is uninstalled or deleted. The system however provides a comprehensive listing of applications for which user settings exist. The user can choose to delete settings for each of the bundles.
Application folders (<tt>/boot/apps</tt> and <tt>/boot/home/<user>/apps</tt>) display the list of installed bundles including information (description, availability of updates, security risk warning), just like the mail folder in BeOS displays emails.
<pre>
#div style="background-color: #EEEEEE; border: 1px solid; margin: 20pt; padding: 5pt;"
'''wkornewald''': The system should automatically remove settings of deleted apps after a certain amount of time. You don't really want the user to manually clean up his system. The cleanup delay should be long enough to allow the user to update an app by deleting the old version and downloading the new version and it should be long enough to allow the user to "undo" his action. Maybe 1-2 months is fine.
'''pulkomandy''': Deleting files without asking doesn't look right to me. Either delete them as soon as the app is removed, or keep them forever. I like Debian/apt way of doing it : when you delete a package, it's listed in the package manager as 'removed, residual config files' and you can remove these from there.
</pre>
==== Dependencies ====
The user does not have to worry about dependencies. If a bundle depends on other bundles, the package manager should make sure they are fulfilled (on run). If a dependency is not fulfilled, the system will ask the user for confirmation and automatically install any required bundles. This requires an internet connection.
Alternatively, a user can download a '''fat bundle''' that includes the dependencies as well.
==== Updates ====
All ''installed software'' can be checked for new versions. For each of the installed applications, the changes with respect to the installed version can be displayed. Updates are flagged as 'strongly recommended' when security problems are known. The user can select which applications he/she would like to update and have the system perform the updates.
By default, the updater tool does not show libraries in order to keep the list of updates as short as possible and understandable by the non-technical user. Libaries should only be updated when there are known problems with them.
=== Implementation ===
In this section the implementation of the system is discussed.
==== Bundles ====
A bundle is a compressed disk image that contains:
*application executable(s) & data
*metadata
***name
***version
***(revision?)
***hash (integrity-check)
***author
***homepage
***license
***category (for grouping applications in the Deskbar menu)
*shortcuts to appear in the Deskbar menu
***a default shortcut to run when the bundle is being "run"
***right-clicking bundle could offer the option of opening a help document about the application
There are a number of different bundle types:
*application
*library
*driver
*font
*...
Library, driver and font bundles have to be installed.
==== Install or not? ====
As bundles have to be compressed for distribution, they will need to be uncompressed at some point. There are two options:
*Before using a bundle, it is decompressed. This is very similar to installing, which many wanted to avoid.
*The bundle's contents are decompressed on access. This is less efficient as decompression needs to be performed on each access, as opposed to only one time during installation. Performance of large applications and heavy games in particular will suffer.
It is possible to split application bundles into two sub-types; those that have to be installed, and those that can be run as-is.
<pre>
#div style="background-color: #EEEEEE; border: 1px solid; margin: 20pt; padding: 5pt;"
'''brecht''': While I initially liked the idea of not having to install software, I now feel that it is not suited for all types of applications and games. While we can make a differentiate between 'large' and 'small' applications and require installation of large apps (or suffer from poor performance), this feels like a bit of a kludge. Is is really that bad to 'install' software once? Installing can be reduced to decompressing and should not bother the user much. If the user knows he has to install '''all''' bundles, there can be no confusion.
'''wkornewald''': I don't fully remember my original proposal (it's been several years :), but I think there's a middle-path: When the bundle is opened for the first time it's decompressed and cached automatically. When the bundle is deleted from the file system the cache is cleaned, too. That way you have the best of both worlds and the user only has a slow first start, but all subsequent app starts will be fast. Maybe the cache itself could be a single uncompressed bundle/image file if that's more efficient than having lots of small files spread over the main file system. A large coherent file can probably be read into memory much faster and should speed up app starts noticeably.
</pre>
==== File System Organization ====
Native Haiku applications are contained in their own directory as before. Organization of ports is more complicated.
==== Merged ====
By means of a union pkgfs (3). All ports are mounted under <tt>/boot/common</tt>.
It is not clear how multiple versions of libraries and applications can be handled in this scheme.
==== Self-contained ====
By means of assignfs (4). Each port receives its own unique assign: <tt>/boot/apps/<port>-<version>-<revision></tt>
<pre>
#div style="background-color: #EEEEEE; border: 1px solid; margin: 20pt; padding: 5pt;"
'''axeld''': I think the best solution would be a unionfs approach: the package file system would just blend in the packages where needed. User packages would be merged with the contents of config/, while system wide ones would be merged with the contents of /boot/common/.
</pre>
==== Settings ====
global settings/user settings
==== Multiple Application Version ====
how to handle
==== Dependency Hell ====
[http://en.wikipedia.org/wiki/Dependency_hell Dependency hell] is a problem mostly for ports. That does not mean it can be ignored. At least in the early years of Haiku, ports will be an important source of software.
==== Avoiding ====
Bundles are always fat bundles. All required libraries are included in the bundle. Problem solved!
However, this very area-inefficient. Nor is it a realistic solution for bundles that depend on large packages like Python or Perl.
==== Tackling ====
In order to solve conflicting dependencies, it is necessary to be able to have multiple versions of a library installed. Even worse, some libraries can be built with different options.
To make this work, it is obvious that a central bundle repository is required: HaikuBits. Alongside offering a browsable directory of software like BeBits, it stores information about dependencies. Dependency information (problems arising from certain combinations of bundles) is updated by the community.
An example. When ABC-1.0 is released, its dependency libfoo is at version 1.2.10. Bundle ABC-1.0 specifies "libfoo >= 1.2.10" as a dependency. Later, when libfoo 1.2.12 is released, it appears that this breaks ABC-1.0. HaikuBits is updated to indicate this: "libfoo >= 1.2.10 && != 1.2.12". When ABC-1.0 is now downloaded from HaikuBits, the bundle contains the updated information. A software updating tool can also check HaikuBits to see whether dependencies are still OK.
Because the act of porting can introduce additional incompatibilities, each port should be tagged with a revision number to uniquely identify it. Revisions can also be used to differentiate between ports with different build options. Specifying build options in the dependency information seems overkill anyway, as we should strive to have as few port revisions as possible (developers should have dependencies installed as bundles before porting).
The bundle metadata needs to be extended to include information about the dependencies:
*minimum/maximum version
*preferred version/revision
*non-working versions/revisions
While bundles will not be available for download for retail software, it still makes sense to record dependency information about it on HaikuBits.
Having an application use a particular library version can be done by manipulating LD_LIBRARY_PATH or by virtually placing the library in the applications directory by means of assignfs or pkgfs.
Note the important difference with typical Linux package management systems. In Linux, the repository typically offers only one version of a particular package. This is the result of keeping all packages in the repository in sync, in order to avoid conflicting dependencies. In the proposed system however, the user is free to install any version of a bundle, as there is no need for any global synchronization of all bundles.
<pre>
#div style="background-color: #EEEEEE; border: 1px solid; margin: 20pt; padding: 5pt;"
'''axeld''': while having a central repository is a good thing, I don't think our package manager should be based on that idea. I would allow each package to define its own sources (the user can prevent that, of course). That way, we avoid the situation of having to choose between outdated repositories, and unstable software (or even having to build it on your own) like you usually have to do in a Linux distribution. The central repository should also be a fallback, though, and try to host most library packages.<br>
Since we do care about binary compatibility, and stable APIs, having a central repository is not necessary, or something desirable at all IMO.
'''brecht''': I agree. I see the repository more as a central entity keeping track of all software versions and the dependencies between them. This dependency information is updated based on user feedback. I don't think it is necessary to have the repository be the one and only source for bundles, however. It can keep instead a list of available mirrors. However, it is probably a good idea to have one large reliable mirror (hosting the most important bundles) managed by Haiku Inc. alongside the repository in order not to be too dependent on third parties.
</pre>
==== libalpm ====
(and it's tool: pacman)
libalpm is the package management library used on ArchLinux, most people know it as "pacman" since that's the main tool to use, however, all the functionality is part of the libalpm library which could be utilized to create a nice GUI frontend for the package manager.
It of course can also be adapted.
It uses libarchive to extract archives, and either libdownload or libfetch to download files - although one can also have it use an external command, like curl or wget.<br>
The current status is this:<br>
As far as libfetch is concerned: compiles and is linked to, but it doesn't really work, so I'm using curl instead - it works like a charm.<br>
The important part: libarchive needed some work to support zip files in a useful way. Basically, it now supports seeking (which it didn't before), the central-directory headers for ZIP files (so it supports stuff like symlinks), and BeOS file attributes! Also, when reading from a source which doesn't allow seeking (... which are... none - on our case) it simply reads the local headers, but can also - if explicitly requested - provide "update"-entries to update the raw data when the central directory is reached (but those are of no importance anymore).
What's good about libalpm? Well, it provides useful configuring mechanisms, it stores dependencies and can also give you a list of which packages require a certain package. It keeps a database containing package information, including a file list. Configuration files in packages can be listed as such, which causes them to be installed as *.pacnew when they are upgraded (unless the new and old files equal - an md5 sum check is used there.)
It provides the ability to use different database directories which allows us to have an automated way of creating package bundles.
For instance, I can set the installdir to /tmp/mypackage and install the game "einstein" including its dependencies there, then move /tmp/mypackage/einstein/common/lib to /tmp/mypackage/einstein/lib, remove the unnecessary manpages, share files (well, usually anything else which is in the common/ folder), and then strip those dependencies from einstein's .PKGINFO file and create a bundled package which I can then install normally to say /boot/apps.
Another useful feature is the possibility to change the root directory. When a package contains a .INSTALL script, libalpm chroot()s into the root directory,
cd()s into the installation directory, and then executes the .INSTALL script (which means, that install-scripts can and should work relative to the installation directory, although, if necessary, the absolute path is available in $PWD)
Also, libalpm works similar to an actual database. It doesn't blindly attempt to install a package, but first check for file conflicts, see if any files need backups or configuration files need to be installed as .pacnew, and then installs a package. If you install multiple packages at once, then it only either installs all of them, or none.
It allows you to find the owning package of a file in the filesystem as well as listing all the files and dependencies of a package.
Where does it get the packages form?
Two possibilities: One can use package files directly - which could be made in such a way that you could also just unzip them. In fact, it might be useful to put the .PKGINFO into the zip file as some extra data which is not unzipped when simply using `unzip´, although package creation is easier if it's just a file.
The other one being repositories. The pacman utility currently allows you to list repositories like this in pacman.conf:
<pre>
[core]
Server = file:///MyRepositories
[devel]
Server = file:///MyRepositories
[public]
Server = http://www.public-repository.com/
</pre>
When you synchronize the repository databases, pacman downloads the file <Server>/<Reponame>.db.tar.gz which contains a list of packages with dependencies.
When you install a package from such a repository, it downloads them from the very same location: <Server>/<Package File>
The repo.db.tar.gz files are currently created using the tools <tt>repo-add</tt> and <tt>repo-remove</tt> provided in the pacman package. Those extract information from the .PKGINFO file and put it into the database which can be used as a repository then.
Here's a little log of using pacman to install a package file, and bundle a package with dependencies together into one package file.
http://stud4.tuwien.ac.at/~e0725517/using-pacman-on-haiku.log.txt
==== Pros ====
*It has been used on archlinux for a long time - so it works.
*It's obviously possibly to compile and use it on haiku
*Since most of its functionality is part of a library, it can be reused to build a GUI-application utilizing libalpm
*pacman also provides scripts for building packages using a PKGBUILD script.
==== Cons ====
*Likely to cause unwanted restrictions in the package management system.
<pre>
#div style="background-color: #EEEEEE; border: 1px solid; margin: 20pt; padding: 5pt;"
'''brecht''': I don't have a detailed view of pacman yet, but as far as I can see it is very similar to your average Linux package manager. As we want software management to be fundamentally different from the way Linux distributions handle it (because it simply is not a very elegant solution), I don't think pacman is a good choice.
'''Blub''': Let me clarify: I was not suggesting to use 'pacman' as a package manager, I was just thinking that its library could be a useful codebase for a package-database, to keep track of dependencies, available packages and updates. It 'could' be used to unpack/install packages into a 'specified' folder, like /boot/apps (and even install dependencies into the same folder if wanted), or, it could just as well be used to simply keep track of where which package has been installed to without worrying about the actual contents.<br>
Although when stripping the code to unpack the archives and keeping track of their files it is indeed better to create something new.<br>
</pre>
=== Brainstorming Results from BeGeistert ===
These features were discussed/written down at BeGeistert:
*Integrated app to add packages
*Knows about repositories
*Defined protocol to add repositories that everyone can use (for example through description files with a special MIME type)
*Multiple installations of the same package (if the software supports it)
*Maintain shared libraries
*runtime_loader uses package info to resolve libraries
*Install packages per user
*Repositories support keys to verify packages
*Package database of installed packages
*Packagemanagement API
*Binary diffing for packages
*Export/publish the set of installed packages to another system
*System updates
*Quality of packages (QA integrated into the process of releasing a package)
*Property of live update possible
=== Package Format ===
A package format has to meet the following requirements:
- It must be able to store BeOS/Haiku file attributes.
- If the package shall be used directly (i.e. without prior extracting) by a package file system, fast random access to the file data must be possible. This disqualifies zipped TAR like formats.
[PackageFormat The Haiku Package format] specifies a format meeting these requirements.
=== References ===
(1) http://www.haiku-os.org/glass_elevator/rfc/installer
(2) http://www.freelists.org/post/haiku-development/software-management-proposal
(3) http://www.freelists.org/post/haiku-development/software-organizationinstallation,8 and http://www.freelists.org/post/haiku-development/software-organizationinstallation,55
<pre>
#div style="background-color: #EEEEEE; border: 1px solid; margin: 20pt; padding: 5pt;"
'''jonas.kirilla''': I hope it's clear enough in reference 3 (above) that my ideas on package management approach it from a different angle. Which may or may not overlap with the use of libalpm. FWIW, I'm not ready to endorse all aspects of this proposal.
</pre>
(4) http://www.freelists.org/post/haiku-development/Pathrelocatable-software-and-assigns
(5) http://www.freelists.org/post/haiku-development/software-organizationinstallation
Other package managers to steal ideas from:
*[http://0install.net/injector-design.html 0install] - probably the most interesting
*[http://en.wikipedia.org/wiki/Klik_(packaging_method) klik]
*[http://www.gnome.org/~alexl/glick/ glick]
*[http://wiki.rpath.com/wiki/Conary Conary]
Useful articles:
*[http://www.osnews.com/story/16956/Decentralised-Installation-Systems/ OSNews: Decentralised Installation Systems] - article by the 0install author
*[http://en.wikipedia.org/wiki/Package_management_system Package management system]
Misc.
*[http://lists.ports.haiku-files.org/pipermail/haikuports-devs-ports.haiku-files.org/2009-June/000516.html Integrating OptionalPackages into Haiku's build system]
docs/develop/packages/PackagingPolicy.rst
+133
View File
@@ -0,0 +1,133 @@
================
Packaging Policy
================
This document defines the policy for creating packages.
Multiple Packages per Software
==============================
Installation files of a software shall be put into separated packages according
to their purpose. For a software "foo":
- Package "foo": Contains all runtime files, i.e. everything needed to "run" the
software. This may include executables (e.g. executable "bin/foo"), shared
libraries (e.g. "lib/libfoo.so"), data files
(e.g. "data/foo/foo-runtime-data").
- Package "foo_devel": Contains only the files needed for development. This
includes header files and static libraries. Shared libraries are not to be
included. Instead the package must declare package "foo" with the matching
version as a requirement.
- Package "foo_doc": Contains the documentation for using "foo".
- Package "foo_devel_doc": Contains the documentation for "foo" development,
like API documentation etc.
- Package "foo_debuginfo": Contains the debug information for the package "foo".
If multiple packages are defined, they must not contain any common files.
If a software contains client and server software that can be used independently
from each other, two separate sets of packages shall be created.
Provides Declaration
====================
A package "foo" must declare the following provided resolvables:
- "foo=<version>" with <version> naming the exact version of the package.
- "cmd:<name>=<version>" for each executable <name> with version <version>
installed in "bin/". This includes a declaration for "cmd:foo", if there is an
executable named like the package.
- "lib:<name>=<version>" for each shared library <name> (not including a suffix,
e.g. "libfoo") with version <version> installed in "lib/".
- "devel:<name>=<version>" for each library <name> (not including a suffix,
e.g. "libfoo") with version <version> for which development files (library
symlinks in "develop/lib" and header files in "develop/headers") are included.
Any instance of '-' in <name> shall be replaced by '_'. If the backward
compatibility of a resolvable is known, a "compat >= <compatibleVersion>" shall
be added accordingly.
Documentation
=============
If a package "foo" provides documentation (which it should, of course), in many
cases that can be provided in different formats:
- Any kind of user documentation belongs in a subdirectory of "documentation"
- Man pages is the preferred format for terminal and should be installed into
the corresponding folders in the subdirectory "man".
- Info files are provided by many packages. If at all desirable, they should
be installed into the subdirectory "info". One problem with info files is
that all packages currently contain a file named "documentation/info/dir",
which supposedly is the list of all available info files, but since each
package provides an instance of this file containing only its own info
files, an arbitrary dir file is made visible via packagefs. The file should
therefore not be include in a package.
- Other documentation for a package foo -- HTML, a simple ReadMe, sample
documents, PDFs, etc. -- goes into subdirectory "packages/foo". If it is
likely that multiple versions of a package may be installed, then a version
string (as appropriate just major, major and minor, or even full (but no
revision)) should be appended, e.g. "package/foo-2" or "package/foo-2.13".
- For a package foo_devel developer documentation, except man and info pages,
should go into "develop/documentation/foo". A version string may be appended
to the directory name as well. When it is unclear what is developer
documentation or it isn't really possible to separate it from user
documentation "documentation/foo" should be used.
Data Files
==========
Data files for a package foo shall generally be placed in a directory
"data/foo". If it is likely that multiple versions of a package may be
installed, then a version string shall be appended. Data (but not
settings/configuration) files generated at run-time shall be placed in
"cache/foo" or "var/foo", depending on the kind of data the files contain. For
data files, both read-only or generated, that are shared between different
packages/software a differently named subdirectory may be used as appropriate
(e.g. font files are placed in "data/fonts").
Writable and Settings Files and Directories
===========================================
All global writable files and directories as well as user settings files and
directories that the package includes or the packaged software creates or
requires the user to create shall be declared by the package (via
GLOBAL_WRITABLE_FILES respectively USER_SETTINGS_FILES in the build recipe) in
the following way:
- A user specific settings file shall never be installed on package activation.
Usually user specific settings files are completely optional. In the rare case
that a software requires a user specific settings, the user will have to
create it manually. In either case, if the package includes a template user
settings file, that should be declared::
USER_SETTINGS_FILES="settings/foo template data/foo/user-settings-template"
If no template file is included, the settings file shall still be declared::
USER_SETTINGS_FILES="settings/foo"
- Since many ported software requires a global settings file or other writable
files, a default version of such a file can be provided and is automatically
installed on package activation. In that case the package must also declare
what shall be done with a user-modified file when the package is updated.
E.g.::
GLOBAL_WRITABLE_FILES="settings/foo keep-old"
"keep-old" indicates that the software can read old files and the
user-modified file should be kept. "manual" indicates that the software may
not be able to read an older file and the user may have to manually adjust it.
"auto-merge" indicates that the file format is simple text and a three-way
merge shall be attempted. If a default settings file is not included in the
package, the settings file shall still be declared, just without the
additional keyword.
In both cases, user settings files and global writable files, the "directory"
keyword can be used to indicate that the given path actually refers to a
directory.
Post-Installation Scripts
=========================
A package may include one or more post-installation scripts. The scripts are
executed whenever the package is activated (for the first time, but also after
package updates). They shall be placed in "boot/post-install" and declared
explicitly by the package (via POST_INSTALL_SCRIPTS in the build recipe). A
post-install script should be considered the last resort. It should only be
used, if there's no reasonable alternative.
docs/develop/packages/PackagingPolicy.wiki
-70
View File
@@ -1,70 +0,0 @@
== Packaging Policy ==
This document defines the policy for creating packages.
=== Multiple Packages per Software ===
Installation files of a software shall be put into separated packages according to their purpose. For a software "foo":
*Package "foo": Contains all runtime files, i.e. everything needed to "run" the software. This may include executables (e.g. executable "bin/foo"), shared libraries (e.g. "lib/libfoo.so"), data files (e.g. "data/foo/foo-runtime-data").
*Package "foo_devel": Contains only the files needed for development. This includes header files and static libraries. Shared libraries are not to be included. Instead the package must declare package "foo" with the matching version as a requirement.
*Package "foo_doc": Contains the documentation for using "foo".
*Package "foo_devel_doc": Contains the documentation for "foo" development, like API documentation etc.
*Package "foo_debuginfo": Contains the debug information for the package "foo".
If multiple packages are defined, they must not contain any common files.
If a software contains client and server software that can be used independently from each other, two separate sets of packages shall be created.
=== Provides Declaration ===
A package "foo" must declare the following provided resolvables:
*"foo=<version>" with <version> naming the exact version of the package.
*"cmd:<name>=<version>" for each executable <name> with version <version> installed in "bin/". This includes a declaration for "cmd:foo", if there is an executable named like the package.
*"lib:<name>=<version>" for each shared library <name> (not including a suffix, e.g. "libfoo") with version <version> installed in "lib/".
*"devel:<name>=<version>" for each library <name> (not including a suffix, e.g. "libfoo") with version <version> for which development files (library symlinks in "develop/lib" and header files in "develop/headers") are included.
Any instance of '-' in <name> shall be replaced by '_'. If the backward compatibility of a resolvable is known, a "compat >= <compatibleVersion>" shall be added accordingly.
=== Documentation ===
If a package "foo" provides documentation (which it should, of course), in many cases that can be provided in different formats:
*Any kind of user documentation belongs in a subdirectory of "documentation"
- Man pages is the preferred format for terminal and should be installed into the corresponding folders in the subdirectory "man".
- Info files are provided by many packages. If at all desirable, they should be installed into the subdirectory "info". One problem with info files is that all packages currently contain a file named "documentation/info/dir", which supposedly is the list of all available info files, but since each package provides an instance of this file containing only its own info files, an arbitrary dir file is made visible via packagefs. The file should therefore not be include in a package.
- Other documentation for a package foo -- HTML, a simple ReadMe, sample documents, PDFs, etc. -- goes into subdirectory "packages/foo". If it is likely that multiple versions of a package may be installed, then a version string (as appropriate just major, major and minor, or even full (but no revision)) should be appended, e.g. "package/foo-2" or "package/foo-2.13".
*For a package foo_devel developer documentation, except man and info pages, should go into "develop/documentation/foo". A version string may be appended to the directory name as well. When it is unclear what is developer documentation or it isn't really possible to separate it from user documentation "documentation/foo" should be used.
=== Data Files ===
Data files for a package foo shall generally be placed in a directory "data/foo". If it is likely that multiple versions of a package may be installed, then a version string shall be appended. Data (but not settings/configuration) files generated at run-time shall be placed in "cache/foo" or "var/foo", depending on the kind of data the files contain. For data files, both read-only or generated, that are shared between different packages/software a differently named subdirectory may be used as appropriate (e.g. font files are placed in "data/fonts").
=== Writable and Settings Files and Directories ===
All global writable files and directories as well as user settings files and directories that the package includes or the packaged software creates or requires the user to create shall be declared by the package (via GLOBAL_WRITABLE_FILES respectively USER_SETTINGS_FILES in the build recipe) in the following way:
*A user specific settings file shall never be installed on package activation. Usually user specific settings files are completely optional. In the rare case that a software requires a user specific settings, the user will have to create it manually. In either case, if the package includes a template user settings file, that should be declared:
<pre>
USER_SETTINGS_FILES="settings/foo template data/foo/user-settings-template"
</pre>
If no template file is included, the settings file shall still be declared:
<pre>
USER_SETTINGS_FILES="settings/foo"
</pre>
*Since many ported software requires a global settings file or other writable files, a default version of such a file can be provided and is automatically installed on package activation. In that case the package must also declare what shall be done with a user-modified file when the package is updated. E.g.:
<pre>
GLOBAL_WRITABLE_FILES="settings/foo keep-old"
</pre>
"keep-old" indicates that the software can read old files and the user-modified file should be kept. "manual" indicates that the software may not be able to read an older file and the user may have to manually adjust it. "auto-merge" indicates that the file format is simple text and a three-way merge shall be attempted. If a default settings file is not included in the package, the settings file shall still be declared, just without the additional keyword.
In both cases, user settings files and global writable files, the "directory" keyword can be used to indicate that the given path actually refers to a directory.
=== Post-Installation Scripts ===
A package may include one or more post-installation scripts. The scripts are executed whenever the package is activated (for the first time, but also after package updates). They shall be placed in "boot/post-install" and declared explicitly by the package (via POST_INSTALL_SCRIPTS in the build recipe). A post-install script should be considered the last resort. It should only be used, if there's no reasonable alternative.
docs/develop/packages/README.rst
+92
View File
@@ -0,0 +1,92 @@
==================
Package Management
==================
This is a short index of the available package management related documentation.
- `Package Management Infrastructure`_ provides an overview of what components
belong to Haiku's package management infrastructure and how they work and
interact.
.. _Package Management Infrastructure: Infrastructure.rst
- `Building Packages`_ gives information on various aspects of the package
building process.
.. _Building Packages: BuildingPackages.rst
- `Boot Volume Directory Structure`_ outlines the directory structure of a
package management powered Haiku boot volume.
.. _Boot Volume Directory Structure: DirectoryStructure.rst
- `Haiku Package File Format`_ specifies in detail the file format of Haiku
package files (HPKG) and Haiku package repository files (HPKR).
.. _Haiku Package File Format: FileFormat.rst
- `Packaging Policy`_ defines the policy for creating Haiku packages.
.. _Packaging Policy: PackagingPolicy.rst
- `Packages Status`_ gives an overview of the packages needed for a Haiku
standard build and their current status.
.. _Packages Status: PackagesStatus.rst
- `Hybrid Builds`_ provides some information regarding hybrid builds.
.. _Hybrid Builds: HybridBuilds.rst
- HaikuDepot_ explains the concept and ideas behind HaikuDepot, the GUI package
manager in the making.
.. _HaikuDepot: HaikuDepot.rst
- Migration_ lists the changes that users should expect when migrating to a
package management Haiku.
.. _Migration: Migration.rst
- `Bootstrapping Haiku`_ explains the process of bootstrapping Haiku and third-party packages.
.. _Bootstrapping Haiku: Bootstrapping.rst
- TODO_ is a list of package management related work still to be done.
.. _TODO: TODO.rst
- `Blog posts`_ on package management (the Batisseur ones are only indirectly
package management related).
.. _Blog posts: https://www.haiku-os.org/tags/package-management/
- `(Old) Package Management Ideas`_ is a collection of thoughts and discussions
regarding package management. It has been partially obsoleted by the progress
on the package management implementation.
.. _(Old) Package Management Ideas: OldIdeas.rst
- http://www.youtube.com/watch?v=rNZQQM5zU-Q&list=PL3FFCD4C6D384A302 is a video
playlist of Ingo and Oliver explaining and demonstrating the package
management branch at BeGeistert 2011.
Below are links to source code related to Haiku's package management.
- Package management has been merged into "master", so see the Haiku_ and
Buildtools_ repositories for that
.. _Haiku: http://cgit.haiku-os.org/haiku/
.. _Buildtools: http://cgit.haiku-os.org/buildtools/
- HaikuPorts_ contains the build recipes of various ports.
.. _HaikuPorts: https://github.com/haikuports/haikuports
- haikuports.cross_ contains the minimal set of build recipes to bootstrap a new
Haiku architecture.
.. _haikuports.cross: https://github.com/haikuports/haikuports.cross
- haikuporter_ is the tool to create binary packages from build recipes.
.. _haikuporter: https://github.com/haikuports/haikuporter
docs/develop/packages/README.wiki
-25
View File
@@ -1,25 +0,0 @@
== Package Management ==
This is a short index of the available package management related documentation.
*[[Infrastructure.wiki| Package Management Infrastructure]] provides an overview of what components belong to Haiku's package management infrastructure and how they work and interact.
*[[BuildingPackages.wiki| Building Packages]] gives information on various aspects of the package building process.
*[[DirectoryStructure.wiki| Boot Volume Directory Structure]] outlines the directory structure of a package management powered Haiku boot volume.
*[[FileFormat.wiki| Haiku Package File Format]] specifies in detail the file format of Haiku package files (HPKG) and Haiku package repository files (HPKR).
*[[PackagingPolicy.wiki| Packaging Policy]] defines the policy for creating Haiku packages.
*[[PackagesStatus.wiki| Packages Status]] gives an overview of the packages needed for a Haiku standard build and their current status.
*[[HybridBuilds.wiki| Hybrid Builds]] provides some information regarding hybrid builds.
*[[HaikuDepot.wiki| HaikuDepot]] explains the concept and ideas behind HaikuDepot, the GUI package manager in the making.
*[[Migration.wiki| Migration]] lists the changes that users should expect when migrating to a package management Haiku.
*[[Bootstrapping.wiki| Bootstrapping Haiku]] explains the process of bootstrapping Haiku and third-party packages.
*[[TODO.wiki| TODO]] is a list of package management related work still to be done.
*[https://www.haiku-os.org/tags/package-management/ Blog posts] on package management (the Batisseur ones are only indirectly package management related).
*[[OldIdeas.wiki| (Old) Package Management Ideas]] is a collection of thoughts and discussions regarding package management. It has been partially obsoleted by the progress on the package management implementation.
*http://www.youtube.com/watch?v=rNZQQM5zU-Q&list=PL3FFCD4C6D384A302 is a video playlist of Ingo and Oliver explaining and demonstrating the package management branch at BeGeistert 2011.
Below are links to source code related to Haiku's package management.
*Package management has been merged into "master", so see the [http://cgit.haiku-os.org/haiku/ Haiku] and [http://cgit.haiku-os.org/buildtools/ Buildtools] repositories for that
*[https://github.com/haikuports/haikuports HaikuPorts] contains the build recipes of various ports.
*[https://github.com/haikuports/haikuports.cross haikuports.cross] contains the minimal set of build recipes to bootstrap a new Haiku architecture.
*[https://github.com/haikuports/haikuporter haikuporter] is the tool to create binary packages from build recipes.
docs/develop/packages/TODO.rst
+59
View File
@@ -0,0 +1,59 @@
These are the TODO items for the Haiku **Package Management**.
packagefs
=========
- If necessary, add a caching mechanism to speed up mounting it.
Package Daemon
==============
- Complete support for extracting and updating settings files: Merge support and
user feedback are still missing.
- Add user notification/interaction support for initial verification
(on start-up).
- Support packages being copied to the ``packages`` directory. Currently only
moving works.
Package building
================
- Define packaging guidelines and create a tool to check packages against those.
- Status: Here's the `wiki page`_ defining the policy. It's still a work in
progress. haikuporter has some policy checking built in already.
.. _wiki page: PackagingPolicy.rst
Package kit/manager
===================
- Add system update support.
- Status: Mostly functional in pkgman (``pkgman full-sync``), but unsupported
in HaikuDepot.
Boot loader
===========
- Safe mode/recovery options:
- Disable packages installed in home.
Package/package repository format
=================================
- Add localization support. More_ info_.
.. _More: http://www.freelists.org/post/haiku-depot-web/Title-localization,18
.. _info: http://www.freelists.org/post/haiku-depot-web/Title-localization,29
- Add support for repository keys (public/private) and package
signing/checksums, so that it is possible to verify that data retrieved from a
repository have not been tampered with.
- Add package sizes to repository. Since there are plans to support xz (or other
high-ratio formats) compressed uncompressed packages for download that are
recompressed for installation, we probably need to discriminate between
download and installation sizes.
- Add support for a faster compression format (e.g. lz4_). As it turns out,
the currently used zlib compression is rather slow (slower than reading
uncompressed data from a slow HD).
.. _lz4: https://lz4.github.io/lz4/
- Add MIME info for types supported by packaged applications
(and sniffer rules?) to the package attributes.
docs/develop/packages/TODO.wiki
-35
View File
@@ -1,35 +0,0 @@
These are the TODO items for the Haiku '''Package Management'''.
==== packagefs ====
**If necessary, add a caching mechanism to speed up mounting it.
==== Package Daemon ====
**Complete support for extracting and updating settings files: Merge support and user feedback are still missing.
**Add user notification/interaction support for initial verification (on start-up).
**Support packages being copied to the <tt>packages</tt> directory. Currently only moving works.
==== Package building ====
**Define packaging guidelines and create a tool to check packages against those.
***Status: Here's the [[PackageManagement/PackagingPolicy| wiki page]] defining the policy. It's still a work in progress. haikuporter has some policy checking built in already.
==== Package kit/manager ====
**Add system update support.
***Status: Mostly functional in pkgman (<tt>pkgman full-sync</tt>), but unsupported in HaikuDepot.
==== Boot loader ====
**Safe mode/recovery options:
- Disable packages installed in home.
==== Package/package repository format ====
**Add localization support. [http://www.freelists.org/post/haiku-depot-web/Title-localization,18 More] [http://www.freelists.org/post/haiku-depot-web/Title-localization,29 info].
**Add support for repository keys (public/private) and package signing/check sums, so that it is possible to verify that data retrieved from a repository have not been tampered with.
**Add package sizes to repository. Since there are plans to support xz (or other high-ratio formats) compressed uncompressed packages for download that are recompressed for installation, we probably need to discriminate between download and installation sizes.
**Add support for a faster compression format (e.g. [https://code.google.com/p/lz4/ lz4]). As it turns out, the currently used zlib compression is rather slow (slower than reading uncompressed data from a slow HD).
**Add MIME info for types supported by packaged applications (and sniffer rules?) to the package attributes.
==== Miscellaneous ====
**Add MIME directory watching to registrar, so it can update the MIME DB caches when packages are de-/activated.
**Get rid of post_install scripts. Do that in the build system.
**Get rid of UserBootscript. Start the scripts in "~/config/settings/boot/launch" from Bootscript instead.
**Update Installer.