1=============
2Hybrid Builds
3=============
4A hybrid build of Haiku used to be a regular Haiku built with gcc 2, also
5including the versions of the system libraries built with gcc 4 (or vice versa),
6so that programs built with either compiler could be run. Package management
7extends that concept and makes it more modular. Since it assigns gcc 2 and gcc 4
8different (packaging) architectures ("x86_gcc2" and "x86"), we can now speak of
9a primary architecture -- the one the system has been built for -- and a
10secondary architecture -- the one the additional set of system libraries has
11been built for. This also fits fine with the x86_64+x86 hybrid option we might
12see in the future.
13
14Since the files for the secondary architecture will live in one or more separate
15packages we gain some flexibility. E.g. one could start out with a non-hybrid
16Haiku and install the packages for the secondary architecture later on, and
17remove them when no longer needed.  In theory there's nothing preventing us from
18supporting multiple secondary architectures (e.g. x86_64+x86+x86_gcc2), though
19that might get somewhat confusing in practice.
20
21The following sections list the requirements for the hybrid concept and the
22packages built for a secondary architecture.
23
24General Requirements
25====================
261. Secondary architecture libraries and add-ons must live in respective
27   "<secondary_arch>" subdirectory, where the runtime loader will only look when
28   loading a secondary architecture executable.
29#. Secondary architecture development libraries and headers must live in
30   "<secondary_arch>" subdirectory, where only the secondary architecture
31   compiler will look for them.
32#. Secondary architecture executables must live in a "<secondary_arch>"
33   subdirectory, which by default isn't in PATH. The executables can be
34   symlinked to the primary architecture "bin" directory, using a symlink name
35   that doesn't clash with the primary architecture executable's name (by
36   appending to the name the secondary architecture name, e.g. "grep-x86"). If
37   there isn't a corresponding package for the primary architecture, the
38   executables may also live directly in the "bin" directory.
39#. Application directories should live in a "<secondary_arch>" subdirectory,
40   unless there isn't a corresponding package for the primary architecture.
41
42Secondary Architecture Package Requirements
43===========================================
441. A secondary architecture package must not conflict with the corresponding
45   primary architecture package, so both can be active at the same time and in
46   the same installation location.
47#. Packages that require a command ("cmd:...") and don't need it to be for a
48   particular architecture shouldn't need to be concerned with the
49   primary/secondary architecture issue. E.g. "cmd:grep" should provide them
50   with a working grep.
51#. Secondary architecture packages providing a command should generally provide
52   both "cmd:<command>" and "cmd:<command>_<secondary_arch>"
53   (e.g. "cmd:grep" and "cmd:grep_x86_gcc2"). The former makes 2. possible. The
54   latter allows for packages to explicitly require the command for the
55   secondary architecture (3. of the general requirements actually implies that
56   provides item). The former should be omitted, when the behavior/output of the
57   command is architecture dependent (e.g. in case of compilers etc.).
58#. Secondary architecture packages providing a library must provide
59   "lib:<library>_<secondary_arch>" (e.g. "lib:libncurses_x86").
60