Date: Wed, 26 Jul 2000 09:17:06 -0500 (CDT) From: "Jeffrey S. Sharp" <jss@subatomix.com> To: freebsd-small@freebsd.org Subject: TinyBSD Documentation Message-ID: <Pine.BSF.4.21.0007260848580.10698-200000@lepton.subatomix.com>
index | next in thread | raw e-mail
[-- Attachment #1 --]
Attached is the current revision of the TinBSD kit user's guide, which
pretty much serves as my design document. Give it a read, all, and tell
me what you think.
===============================
Jeffrey S. Sharp (XorAxAx)
jss@subatomix.com
-----BEGIN GEEK CODE BLOCK-----
Version 3.12
GCS/IT/MU d-@ s-:+ a21 C++(++++) UBL+(+++$)> P L+(+++$)>
E+> W++ N+(++) o? K? w++$> !O M(-) !V PS+ PE Y PGP- t+
5 X+ R(+) tv+ b+ DI++(+++) G++ e> h--- r+++ y+++
------END GEEK CODE BLOCK------
[-- Attachment #2 --]
-*- mode: Text; fill-column: 72; -*-
$Id: README,v 1.5 2000/07/26 14:17:47 jeff Exp $
TinyBSD Development Kit
Copyright 2000
Jeffrey S. Sharp. All rights reserved.
See the file COPYRIGHT for legal information.
User's Guide
========================================
1. What is TinyBSD?
TinyBSD is an adaptation of the FreeBSD operating system specially
suited for deployment it tight spaces. TinyBSD is designed to run with
minimal amounts of memory, storage space, and processing power, and is
highly user-configurable. Because it is essentially a stripped-down
FreeBSD, TinyBSD gives developers the power, capability, and stability
of Unix as well as the thousands of available FreeBSD applications and
ports -- all in a very small package.
Possible applications of TinyBSD include embedded devices, network
appliances, boot/demo/fixit floppies, and custom install CDs.
A TinyBSD distribution is configured and built with this TinyBSD
Development Kit. Users provide sets of configuration files called
'buildtypes', that guide the TinyBSD kit in the construction of TinyBSD
distributions.
========================================
2. Features of TinyBSD
Instead of providing a single default configuration which all buildtypes
inherit from, the TinyBSD kit uses a hierarchial tree of buildtypes that
behaves much like a class inheritance hierarchy in object-oriented
programming. Each buildtype can have any number of child buildtypes,
and children inherit configuration from their parents. This inheritance
of configuration helps to reduce duplication of work.
All configuration information needed by the TinyBSD kit has been
consolidated into four types of configuration files with a consistent
syntax.
While the TinyBSD kit currently only supports disk-type targets (i.e.,
those that can be worked on by fdisk(8), disklabel(8), and newfs(8)), it
can be easily extended to handle other types, such as CD-ROMs. For
disk-type targets, an arbitrary number of filesystems can be placed on
each disk, and each target may be built to a disk image or directly to a
physical device. Both sliced and unsliced disks are supported.
A single TinyBSD buildtype can create an arbitrary number of disk
images, CD-ROMs, etc. Full support exists for creating multi-disk
distributions. TinyBSD also supports placing one disk image within
another disk to create, for instance, a MFS (ramdisk) root filesystem.
Binaries can be placed on a TinyBSD filesystem in two different ways.
First, they can simply be copied from the build host as files. Second,
they can be placed in a 'crunched binary'. In a crunched binary,
multiple programs and the libraries they depend on are concatenated into
one large binary, which saves both storage space and memory. For more
information about crunched binaries, see crunchgen(1).
There are three ways to place a kernel on a TinyBSD filesystem. First,
a kernel can be left as a normal kernel and copied directly to the
filesystem. Second, a kernel can be gzipped, requiring a third stage
bootblock, loader(8), to uncompress it at boot time. Third, a kernel
can be compressed with kgzip, which enables the kernel to uncompress
itself without any help. Note that in all three cases, the kernel is
built automatically by the TinyBSD kit.
========================================
3. Directory Layout And Inheritance
Each buildtype has a certain directory structure:
some_buildtype/
build/ _______
Makefile@ \______ Some makefiles
Makefile.inc _______/
build.conf \
dev0.conf \
dev1.conf \
fs0.conf >--- Some conf files
fs1.conf /
fs2.conf /
kern0.conf _______/
...
custom/ _______
Makefile _______>------ A custom makefile
foo.txt \
bar.sh >----- Some custom files
baz.gz _______/
... _______
for_fred/ \
for_joe/ >----- Some subdirectories
demo_version/ _______/
...
Each buildtype has a 'build' subdirectory. This is where conf files for
the buildtype go. There will be at least four. Also in the build
subdirectory are a symbolic link back to the top-level makefile, a
Makefile.inc for specifying custom targets, and a 'custom' subdirectory.
The custom subdirectory is the place to put any nonstandard or user-made
files needed in the distribution, and can have its own Makefile to
automate the process of building non-static custom files. Besides the
mandatory 'build' subdirectory, a buildtype directory contains zero or
more other subdirectories. These subdirectories contain child
buildtypes. Each child buildtype has a layout just like this one.
There are four species of conf files: build, device, filesystem, and
kernel. Every TinyBSD buildtype has exactly one 'build.conf' file,
which specifies options global to the buildtype, and one or more of each
of the other types of conf files. They are named 'xxxxy.conf', where
xxxx is one of the abbreviations dev, fs, or kern, and y is an
identification character. Examples of valid names are: dev0.conf,
fs0.conf, kern9.conf, devq.conf, and kernP.conf.
Child buildtypes inherit the configuration of their parent. For each
device, filesystem, or kernel conf file of the parent, a child buildtype
has several options:
1) The child may have a conf file of the same name with supplemental
configuration information. This can either make additions to or take
away from the parent's configuration.
2) The child may have an empty conf file of the same name. This causes
the parent's configuration (from that file) to be used without
modification.
3) The child may not have a conf file of the same name. This causes the
parent's configuration (from that file) to be thrown out completely.
Children can also have device, filesystem, or kernel conf files that
don't appear in their parent's set; these files start a fresh unit of
configuration and inherit nothing from the parent.
Build options specified in a buildtype's 'build.conf' file are not
inherited.
In the top-level directory of the TinyBSD kit exists the top-level
buildtype which provides a small set of defaults that are inherited by
all buildtypes, the makefile that serves as the interface to the TinyBSD
kit, and a 'stuff' directory that' directory that contains private stuff
needed by the TinyBSD kit (currently only a big script that builds
makefiles from the user conf files).
========================================
4. The Conf Files
[More information is needed here about the general format of all conf
files.]
========================================
4.1 Build Conf Files
Each buildtype must have exactly one 'build.conf' file. These files
specify options specific to each build type and do not participate in
the inheritance scheme. The following commands are supported:
set abstract <value>
Determines whether or not the buildtype is "abstract". If a
buildtype is abstract, then it is used for inheritance purposes
only, and make will refuse to build it. <value> may be 'yes' or
'no'.
set devorder <x> <y> <z> ...
Determines the order in which device conf files are processed by
make. If a filesystem in a buildtype includes a disk image
produced by one of the buildtype's device conf files (for
instance, a MFS root filesystem image), then this directive
should be used to ensure that the image is built before the
containing filesystem's device. <x>, <y>, <z>, etc. are the
identification characters, in order, of the device conf files.
For example, to specify that 'dev1.conf' should be processed by
make before 'dev0.conf', the correct command would be 'set
devorder 1 0'.
========================================
4.2 Device Conf Files
Device conf files specify configuration information for the physical
device(s) that a TinyBSD distribution will be stored on. The following
command is absolutely required:
set target_type <type>
Determines the overall process used to build the device. <type>
must be one of the supported target types:
disk Disk-type targets
cd-rom CD-ROM targets (NOT IMPLEMENTED YET!)
Depending on the setting of 'target_type', different commands are
relevant in the rest of the device conf file.
========================================
4.2.1 Disk Targets (target_type = disk)
Disk targets are targets that act like conventional disks to the BSD
utilities fdisk(8), disklabel(8), and newfs(8). Device conf files for
disk targets support the following commands in addition to 'set
target_type':
set target <target>
Required. Determines the physical destination of the device
when built by make. <target> may be one of:
image Build a disk image
<special-file> Build directly to a physical device (ad0, etc.),
where <special-file> is the name of the
appropriate special file.
set use_slices <switch>
Required. Determines whether or not the device should be sliced
with fdisk. <switch> must be 'yes' or 'no'.
set image_size <size>
Required for disk images. Sets the size of the disk image to
<size> kilobytes.
set image_name <name>
Required for disk images. Sets the name of the disk image file
to <name>.
set geometry <c> <h> <s>
Required. Specifies the geometry of the physical target device
or of the virtual disk if building a disk image. <c>, <h>, and
<s> are cylinders, heads, and sectors, respectively.
add slice <num> <type> <offset> <sectors>
One or more required if slices are used. Slice <num>, of
<type>, will be defined in the slice table of the target device,
starting at <offset> and continuing for <sectors>.
add label <slice> <type> <disk> <sectors>
One or more required. The specified <slice> will be
disklabeled. For target devices not using slices, specify slice
0. The values of <type>, <disk>, and <sectors> will be placed
in the corresponding fields in the label.
add partition <slice> <part> <offset> <sectors> <fstype> \
<fsize> <bsize> <bpg>
The partition <part> will be defined in the label for <slice>.
For target devices not using slices, specify slice 0. The
partition will start at sector <offset> (relative to the
beginning of the slice) and continue for <sectors>. <fstype>,
<fsize>, <bsize>, and <bpg> are the filesystem type, fragment
size, block size, and blocks per group, respectively.
add fs <slice> <part> <fsid> <newfs_opts>
The partition <part> on <slice> will be formatted with newfs(8),
and a filesystem (configured with a filesystem conf file) will
be placed on <part>. For target devices not using slices,
specify slice 0. <fsid> is the identification character of the
appropriate filesystem conf file. Extra options to newfs can be
specified with <newfs_opts>
========================================
4.2.2 CD-ROM Targets (target_type = cd-rom)
[CD-ROM targets are not implemented yet. Come back later. :P]
========================================
4.3 Filesystem Conf Files
Filesystem conf files tell the TinyBSD kit which entries should be
placed in a particular filesystem in a TinyBSD distribution. Note that
paths on the TinyBSD filesystem are written in filesystem conf files as
*absolute* paths, just as if the TinyBSD filesystem were mounted root.
The following commands are supported:
add dir <dest>
The directory <dest> will be created on the filesystem.
add file <dest> [<src>]
The file <dest> will be created on the filesystem by copying
from <src>. <src> refers to a file on the build host, not the
TinyBSD filesystem. If <src> is not specified, the file will be
copied from the same absolute address as specified by <dest>.
Wildcards are not supported.
add dev <dest>
The special files resulting from running 'MAKEDEV <dest>' will
be placed in the /dev directory of the filesystem. Note that
one of these lines usually results in multiple special files!
add fifo <dest>
The FIFO <dest> will be created on the filesystem.
add hlink <dest> <src>
The file <dest> on the filesystem will be created as a hardlink
to <src>. <src> refers to a file on the TinyBSD filesystem.
Wildcards are not supported.
add slink <dest> <src>
The file <dest> on the filesystem will be created as a symbolic
link to <src>. Wildcards are not supported.
add srcdir <dir>
For crunched binaries. Adds the directory <dir> to the list of
directories searched for program sources. Synonymous with the
'srcdirs' configuration command of crunchgen(1).
add prog <prog>
For crunched binaries. The program <prog> will be added to the
filesystem's crunched binary and will appear in the /bin
directory on the filesystem. Synonymous with the 'progs'
configuration command of crunchgen(1).
add progln <prog> <link>
For crunched binaries. The file <link> is created in the /bin
directory as a hardlink to the crunched binary as another name
for the program <prog>. Synonymous with the 'ln' configuration
command of crunchgen(1).
add progopt <prog> <opt> <val>
For crunched binaries. Specifies a special option <opt> to help
program <prog> be built. Synonymous with the 'special'
configuration command of crunchgen(1).
add lib <lib>
For crunched binaries. Specifies a library to be linked with
the crunched binary. Synonymous with the 'libs' configuration
command of crunchgen(1), except that libraries are *not*
specified with '-l' (i.e., say 'util', not '-lutil').
add makevar <var> <val>
For crunched binaries. <val> will be appended to the value of
<var> in the environment when make runs to build the crunched
binary. Use this to specify special CFLAGS or other
environment hacks to get programs to coexist happily in the
crunched binary.
rem dir <dest>
Nullifies a matching 'add dir' command.
rem file <dest>
Nullifies a matching 'add file' command.
rem dev <dest>
Nullifies a matching 'add dev' command.
rem fifo <dest>
Nullifies a matching 'add fifo' command.
rem hlink <dest>
Nullifies a matching 'add hlink command.
rem slink <dest>
Nullifies a matching 'add slink' command.
rem srcdir <dir>
For crunched binaries. Nullifies a matching 'add srcdir'
command.
rem prog <prog>
For crunched binaries. Nullifies a matching 'add prog' command,
as well as all 'add progopt' and 'add progln' commands for
program <prog>.
rem lib <lib>
For crunched binaries. Nullifies a matching 'add lib' command.
rem makevar <var> <val>
For crunched binaries. Undoes a matching 'add makevar' command.
set kernel <kernid> <method>
The kernel with identification character <kernid> (created by
compiling a kernel for the kernel conf file with the same
identification character) will be placed on the filesystem
according to <method>. Valid <method>s are:
normal The kernel is copied to /kernel
gzip The kernel is gzipped to /kernel.gz
kgzip The kernel is kgzipped to /kernel.kgz
set parms <dest> <user> <group> <mode>
Sets permissions and ownership for the file <dest>. <user> and
<group> are the UNIX user and group names or numbers of the
intended ownder, and <mode> should be a traditional octal
file-mode number.
========================================
4.4 Kernel Conf Files
Kernel conf files tell the TinyBSD kit what devices and options are
wanted in a kernel, just like regular FreeBSD kernel configuration files
used by '/sbin/config'. Their formats are also quite similar. The
following commands are supported:
set machine <machine>
Equivalent to 'machine <machine>' in traditional FreeBSD kernel
configuration files.
set maxusers <num>
Equivalent to 'maxusers <num>' in traditional FreeBSD kernel
configuration files.
add cpu <cpu>
Equivalent to 'cpu <cpu>' in traditional FreeBSD kernel
configuration files.
add option <option>
Equivalent to 'options <option>' in traditional FreeBSD kernel
configuration files.
add device <device-spec>
Equivalent to 'device <device-spec>' in traditional FreeBSD
kernel configuration files.
add pseudo <pseudo-spec>
Equivalent to 'pseudo-device <pseudo-spec>' in traditional
FreeBSD kernel configuration files.
rem cpu <cpu>
Nullifies a matching 'add cpu' command.
rem option <option>
Nullifies a matching 'add option' command.
rem device <device-spec>
Nullifies a matching 'add device' command.
rem pseudo <pseudo-spec>
Nullifies a matching 'add pseudo' command.
========================================
5. Creating TinyBSD Buildtypes
[More here later. For now, just look at the example stuff. This part
needs to be more or less a complete how-to in contrast with the above
reference. Possibly I should consider working through an example that
illustrates usage of most of the basic options?]
========================================
6. To Do
* Implement way much more checking for user errors. It's too easy to
screw stuff up without knowing why.
* Construct many more example buildtypes.
* Improve this file.
help
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.BSF.4.21.0007260848580.10698-200000>