_ __ ___ __ _ _ __ ______ _ __ __ _
| '__/ _ \ / _` | '__|______| '_ \ / _` |
| | | (_) | (_| | | | | | | (_| |
|_| \___/ \__,_|_| |_| |_|\__, |
__/ |
|___/
############
# Overview #
############
roar-ng is a generic GNU/Linux distribution building system.
It provides an architecture-independent, flexible and portable infrastructure
for the creation of fast and portable "live" GNU/Linux distributions. It
provides support for the binary package format and repositories of various
GNU/Linux distributions.
The development of roar-ng started as a collection of source hacks of Woof (the
Puppy Linux build system) and evolved into a complete, independent
re-implementation. It provides advanced features not found in Woof, such as
parallel downloads, automatic package splitting, simple branding and easy
porting to different processor architectures.
#############################################
# Supported Architectures and Distributions #
#############################################
Packages originating in the following distributions are supported:
- Slackware
- Debian GNU/Linux
- Arch Linux
- Ubuntu
- CentOS
- Fedora
- Raspbian
- Subito GNU/Linux (e.g packages built through roar-ng itself)
Distribution support is provided by sub-directories under the "distro"
directory.
#########
# Usage #
#########
Before roar-ng can be executed to produce a distribution, it must be properly
configured. Its configuration resides under the "conf" directory and consists
of three files:
- bootrc - various boot-related or system initialization parameters, such as
the console font.
- distrorc - the distribution's details, such as its name, version and most
importantly, its target processor architecture.
- package_list - the list of packages included in the distribution's bootable
media. Entries in the file have a special syntax and consist
of four fields: the distribution the binary packages come
from, a meta-package name (e.g "utilities" for a text editor
and a calculator), the names of packages (i.e the exact names,
as the source distribution uses) to include and how to split
the result package.
Just in case it isn't clear enough: here's another explanation. roar-ng reads
a package list, which consists of entries which describe "meta-packages", which
are "big packages" that consist of multiple packages of a supported
distribution. For instance, it is possible to group a package (for example,
Bash) with its dependencies (e.g readline) as one meta-package, like this:
debian|bash_and_deps|bash,readline|exe,dev,doc,nls
The fourth field (e.g the package splitting rules) can be confusing. Its syntax
is consistent: each of the tokens ("exe", "dev", "doc" or "nls") can be suffixed
with the ">" operator, followed by another, to change the way the meta-package
is split. When a package is processed by roar-ng, it gets split into four parts:
the main package, development files, documentation and language support files.
Thse tokens represent those parts: for example, "exe,dev,doc>dev,nls" will
instruct roar-ng to place all documentation alongside the development files.
Once the configuration is ready, roar-ng can be executed. It consists of four
independent scripts:
- 0setup, which downloads package lists from repositories and converts them to
a common, simple format.
- 1download, which downloads all packages included in the distribution.
- 2createpackages, which extracts, optimizes, splits and processes the
packages.
- 3builddistro, which builds a bootable media image. It accepts one parameter:
the media type. Each media has a script under the "media" directory, which
builds an image.
- 4buildpackage, an optional script which builds a binary package from source,
using chroot and 3builddistro's result. It accepts the package name as a
parameter.
Always use a recent snapshot of roar-ng. Since its development model is based on
incremental improvements, rather than "stable" releases, always obtain a fresh
copy of the "master" branch before using it.
################
# Contributing #
################
If you wish to contribute to roar-ng's development, there are many things you
can do (in the following priority):
- Fix bugs.
- Locate and fix inefficiencies.
- Add support for another bootable media (e.g a SD card image for your favorite
SoC).
- Add support for another distribution.
- Add bits of documentation.
The easiest way to begin your development is obtaining your own copy of roar-ng,
so you have something to work on. Clone the code repository or manually maintain
a copy.
Before you send a request to merge your changes, please:
- Make sure your code doesn't conflict with roar-ng's current state, due to
changes between time you began your development and the present.
- Make sure your code is easy to understand, simple as possible, efficient and
matches roar-ng's coding style.
- Document your code.
- Make sure you have a full history of changes; always document changes. Pay
attention to issues you solved and interface changes.
- Make sure your code is as future-proof as possible.
- Make sure your code doesn't have a hard dependency on a third-party
component (e.g a parser). This is required to keep roar-ng independent.
The actual code should be accompanied by all this information. If everything
seems good (which is a very subjective thing), it might be merged into roar-ng
and you well be credited. However, no guarantees are made.
Any code contributed to roar-ng should conform with its license. Code which
doesn't simply won't be merged.
#####################
# Legal Information #
#####################
roar-ng is licensed under the GPLv3 license, see COPYING for the license text.
For a list of its authors and contributors, see AUTHORS and THANKS.
The ASCII art logo at the top was made using FIGlet (http://www.figlet.org/).