targets/i386/WinBook: config changes
[CDN/Mosi.git] / docs / spec
1 docs/        - Project documentation
2   spec       - Specification
3 script/      - Build scripts
4   lib/       - Script libraries (shlib compatible)
5   burn       - Burn a firmware to a card (uses misc/clpbar for status)
6   gencard    - Assemble everything into a card image
7   geniso     - Assemble root filesystem into an iso9660 image (requires sysutils/cdrtools)
8   gentree    - Assemble filesystem from world, pkgs, and overlay; carve out confpacks
9   genufs     - Create a UFS filesystem and populate it with files (superseded by makefs)
10   genuzip    - Compress iso9660 image into geom_uzip image
11   loadconf   - I'm not sure...
12   makepkg    - Libraries to build packages against a specific world
13   makeworld  - Script to build a world from a seed and src
14   push       - Push source tree to build server (requires net/rsync)
15 src/         - Going away
16 targets/     - Contains system targets (world, ports, runtime config)
17   config/    - Generic configuration for all targets
18   amd64/     - Arch-specific targets
19     config/  - Generic configuration for all amd64 targets
20     GENERIC/ - Generic target, relies on worlds/amd64/GENERIC
21   i386/      - Arch-specific targets
22     config/  - Generic configuration for all i386 targets
23     GENERIC/ - Generic target, relies on worlds/i386/GENERIC
24 worlds/      - Contains worlds (config and root tree of a given base system build)
25   config/    - Generic configuration for all worlds
26   amd64/     - Arch-specific worlds
27     config/  - Generic configuration for all amd64 worlds
28     GENERIC/ - Generic world (Empty src.conf, GENERIC kernel config file)
29   i386/      - Arch-specific worlds
30     config/  - Generic configuration for all i386 worlds
31     GENERIC/ - Generic world (Empty src.conf, GENERIC kernel config file)
32 seed/        - Contains seed builds for building a world
33   base/      - Location of base tarballs
34     amd64/   - Arch-specific seed
35     i386/    - Arch-specific seed
36   distfiles/ - Distfile tarballs for port builds
37 Makefile     - Makefile to build it all
38
39 Files in config directories are overlaid completely, and are not merged nor successively applied. For instance, a file with the same name in targets/amd64/config will cause the file in targets/config to be ignored; likewise for a file in targets/amd64/GENERIC/config.
40
41 seed/ is used to seed the initial chroot for building a world.
42
43 A world is a set of config files (src.conf, kernconf) that generates a particular base system build, along with the base system build generated by those config files. These are built off of whatever is in /usr/src at the moment.
44
45 Layout for worlds: (All but config/ are created as needed, and obliterated on clean)
46 worlds/
47   <arch>/
48     <CONF>/
49       config/
50         <CONF>    - Kernel config file for this world; copied to /usr/src/sys/<arch>/conf/<CONF> before build
51         src.conf  - Base system build configuration file; copied to /etc/src.conf before build
52       src@        - Symlink to source tree to use for build; assume /usr/src if missing
53       chroot/     - Chroot directory for isolating builds; seeded by seed/base/<arch>/base.?? before build
54       log/        - Logfiles generated by build system go here
55       obj/        - Object file directory; null-mounted onto /usr/obj before build
56       root/       - Final world image ready for use
57
58
59 A target is a set of config files (make.conf, leaf_ports, port_options) and a system overlay that takes a given world and transforms it into a viable system, which is then carved up and packaged into a firmware.
60
61 Layout for targets: (All but config/ and world@ are created as needed, and obliterated on clean)
62 targets/
63   <arch>/
64     <CONF>/
65       config/          - Target configuration goes here
66         make.conf      - Port build configuration file; copied to /etc/make.conf before build
67         port.options/  - Options framework config files, generated by 'make config' in a port directory;
68           <portname>/  -  copied to /var/db/ports/ before build and scavenged therefrom afterwards
69             options    - 
70         port.lst       - List of leaf ports to build and install; dependencies will be installed automatically
71         conf/          - Confpack configuration: md_size files and previous save cpios
72         overlay/       - A tree of files to be placed into the target filesystem prior to package installation
73         patch/         - Patches applied to the target filesystem after all packages are installed
74         whiteout.lst   - Any filenames that exist in here will be deleted; files with 'rm -f', directories with 'rm -rf'
75       ports@           - Symlink to ports tree to use for build; assume /usr/ports if missing
76       world@           - Symlink to the proper world against which this target is to be built
77       log/             - Logfiles generated by build system go here
78       chroot/          - Chroot directory for isolating builds; seeded by world/root, so make sure the target world is built first
79       bdeps/           - Port build dependencies; not installed in the final image, but useful for reducing build time of ports, since the chroot is cleared out after every build
80       pkg/             - Assembled binary packages to be installed in final image
81       tree/            - Directory for assembling final image
82
83 Packages are built for a world, but specific to a target because they may have target-specific port_options or make.conf tweaks applied.
84
85 Whiteout list files are simple lists, one pathspec per line, of target objects to delete after overlays, packages, and patches are applied. Each line should be relative to the root of the target filesystem image. The entry will be ignored if it resolves to a pathspec that does not exist within the target image. The entry will be ignored with a warning if it resolves to a path that falls outside of the target image's build directory (${sroot}), or if it points to a file contained within a non-directory object (such as /etc/fstab/none when /etc/fstab is not a directory)