_ __ ___   __ _ _ __   ______   _ __   __ _
| '__/ _ \ / _` | '__| |______| | '_ \ / _` |
| | | (_) | (_| | |             | | | | (_| |
|_|  \___/ \__,_|_|             |_| |_|\__, |
                                        __/ |
                                       |___/

roar-ng is deprecated; roar-ng II is the future ... and it's here.
See https://github.com/iguleder/roar-ng-ii.

############
# 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 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.

The name "roar-ng" was originally a pun on the name "Woof". roar-ng's early
prototypes were called "Moo", "Meow", "Tweet" and finally, "Roar". The latter
was the first to show potential and roar-ng is originally a complete rewrite
of it.

#########
# Goals #
#########

roar-ng's key goals are:
 - Be simple.
 - Be generic and independent.
 - Be as thin as possible and provide extra functionality (e.g support for a new
   distribution) via a file system hierarchy, rather than modification of the
   core.

roar-ng provides a simple API for all operations performed in order to build a
distribution (e.g package search, file download, etc') via one common core
("functions") and consists of scripts built on top of it.

#############################################
# Supported Architectures and Distributions #
#############################################

roar-ng supports packages of the following distributions:
 - Slackware
 - Debian GNU/Linux
 - Arch Linux
 - Ubuntu
 - CentOS
 - Fedora
 - OpenSUSE
 - Mageia
 - Raspbian
 - Subito GNU/Linux (e.g packages built through roar-ng itself)

roar-ng is architecture-independent; it can be used to build a distribution for
any processor architecture, as long as there are binary packages for it and
roar-ng is able to produce an image of a supported bootable media.

Each supported distribution has its own sub-directory under the "distro"
directory, containing tools required to handle its package format and
repositories.

Expanding roar-ng's distribution or architecture support is easy and does not
involve changes in existing code: this is one of its main design goals and key
strength.

#################
# Configuration #
#################

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.

The package list is a text file containing package entries; each line contains
one entry, which corresponds to a group of packages. Package entries
consist of four fields, delimited by the "|" character:
 - The distribution the packages come from.
 - A name for the package group.
 - A comma-delimited list of packages included in the group.
 - How to split the result package.

The fourth field can be confusing; in most cases, it will contain the sane
default of "exe,dev,doc,nls". However, it can be also used to affect how roar-ng
splits the result package, by suffixing one of the tokens with ">", followed by
another, e.g "exe,dev,doc>dev,nls". Each token stands for a part of the package:
the main package, development files, documentation or language support files.
Once a token is suffixed this way, the relevant part of the package gets merged
into another: in this example, documentation ("doc") gets redirected into the
development files ("dev") part.

Remember, intimate knowledge of the contents of packages and proper use of
package splitting rules (another key strength of roar-ng) are the key for the
creation of compact, simple and tidy distributions.

#########
# Usage #
#########

roar-ng consists of independent scripts, intended to run in a given order, with
the roar-ng directory as the working directory.

The scripts are:
 - 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 is built through a script under the "media"
   directory.
 - 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 and cannot be used for cross-compilation; it must run on a host
   distribution of the same processor architecture as the result package's one.

roar-ng's development model is based on incremental improvements, rather than
"stable" releases. Therefore, always obtain a fresh snapshot 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.

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 will 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/).