source: freewrt/docs/handbook/user/00-allinone.tex@ f84929f

\chapter{Introduction}

Welcome to FreeWRT! This handbook covers the building, installation and usage
aspects of the FreeWRT 1.0 Linux distribution.  FreeWRT is a portable, secure
and functional Linux distribution for embedded systems. As FreeWRT is a source
code distribution, it does not provide any pre-compiled firmware for embedded
systems. The latest version of this document is always available at the
FreeWRT website. If you have any comments, criticism or found some wrong
description, please send us an eMail to freewrt-handbook@freewrt.org, we are
always happy about getting feedback to this document, and will try to update
or correct the issues mentioned by you.

The handbook is split into five distinct sections. Appliance Development Kit
covers the building of FreeWRT firmware images. The second section, Installing
FreeWRT, covers all aspects regarding the installation and deinstallation of
FreeWRT firmware images. The third section is a detailed description of the
startup process of FreeWRT.  The fourth section, Using FreeWRT, covers
administrational tasks, such as network configuration, the FreeWRT
configuration filesystem, package management and update mechanism. The last
section helps troubleshooting problems and recovering a bad firmware
installation. The appendix contains board specific information. For FreeWRT
1.0 these are only Broadcom based embedded systems.

The intended audience for this handbook are advanced users with basic
knowledge about Linux, networking and software development. The reader should
be aware of basic command line tools, the vi editor and a shell. FreeWRT does
not contain any high level administration tools (e.g. web based
administration) and is fully configured via command line.

\section{Typographic Conventions}

Examples starting with \# indicate a command that must be invoked as super
user. You can use su to gain super user privilges.

\begin{Verbatim}
# fwcf commit
\end{Verbatim}

Examples staring with \$ indicate a command that can be invoked as a normal
user.  The default user account on a freshly installed FreeWRT system is
,,admin''.

\begin{Verbatim}
$ cat /etc/banner
\end{Verbatim}

\chapter{Appliance Development Kit (ADK)}

Our appliance development kit is called ,,buildroot''. The ADK is the core of
FreeWRT and contains all scripts and sources to create firmware images for
every supported embedded system. FreeWRT 1.0 supports the following embedded
systems:

\begin{itemize}
\item Asus WL500g
\item Asus WL500g deluxe
\item Asus WL500g premium
\item Linksys WRT54G v1.0
\item Linksys WRT54G v1.1
\item Linksys WRT54G v2.0
\item Linksys WRT54G v2.2
\item Linksys WRT54G v3.0
\item Linksys WRT54G v3.1
\item Linksys WRT54G v4.0
\item Linksys WRT54GS v1.0
\item Linksys WRT54GS v1.1
\item Linksys WRT54GS v4
\item Linksys WRT54G3G
\item Netgear WGT634u
\end{itemize}

In this release we only support the Linux 2.4 kernel. The ADK contains over
300 software packages.

\section{Prerequisites}

Here is a list of all supported and tested host systems. The host system is
needed to create a firmware for your embedded system.

\begin{itemize}
\item Debian GNU/Linux 3.1 or newer
\item Gentoo Linux
\item Ubuntu Dapper Drake or newer
\item Fedora Core 4 or newer
\item OpenBSD 3.9 or newer
\item MirOS BSD
\end{itemize}

Please install the following software, which is needed to build a basic
firmware image. If you choose more packages some more prerequisites might be
needed. Buildroot will warn you about any software you need to install to
compile a specific package.  Here is a list of the required software:

\begin{itemize}
\item gcc3 or higher
\item g++
\item binutils
\item patch
\item gzip
\item bzip2
\item unzip
\item flex
\item bison
\item GNU make
\item zlib (+headers)
\item ncurses (+headers)
\item (g)libc headers
\item subversion
\item perl
\end{itemize}

The buildroot checks for the required versions of these tools in advance.

To build FreeWRT with buildroot it is recommended to have an unprivileged
user. Please \underline{never} build FreeWRT as super user. Because all necessary source
tarballs are downloaded from the internet automagically, your host system
needs a working internet connection.

\section{Getting the source}

Now go to a directory where you want to build the firmware. Depending on the
features you select you will need about 2.5-5 GB free disk space. This
includes the buildroot itself, any source archives which will be downloaded
and their extracted copies (for compiling).

To get the initial FreeWRT 1.0 buildroot try one of these commands:
\begin{Verbatim}
$ svn co http://www.freewrt.org/svn/branches/freewrt_1_0 freewrt
$ svn co svn://www.freewrt.org/branches/freewrt_1_0 freewrt
\end{Verbatim}

After successfully downloading, enter the directory:

\begin{Verbatim}
$ cd freewrt
\end{Verbatim}

This directory will be referred to as the ADK root later on.

\section{Some Theory First}

Building a FreeWRT firmware image is just like building a new Linux kernel,
but a little more complex. There is a ncurses-based configuration menu at the
beginning, the changes made are saved into a file named ,,.config'' in the ADK
root. The build is done by the various Makefiles, compiling and linking the
sources together accordingly to the symbols defined in ,,.config''.

Unlike kernel compilation, FreeWRT needs to be cross-compiled always. This
leads to special premises, as most of the tools need to be specially build.
But no panic, FreeWRT will do this all for you. In fact, this is done at the
second run of \texttt{make} (the first one opens the configuration), and
therefore can be seen as part of the first firmware build.  For clarity
though, we will discuss these two things separately.

\section{Preparing the Build Process}

After downloading the FreeWRT ADK, it's time to prepare the ADK for the
building of firmware Images (for explanations see the chapter above).

\subsection{Creating A Configuration}
The first step is to run \texttt{make}. After checking some prerequisites (see
,,Troubleshooting'' below for aid in problems), a console based configuration
menu should start. Theoretically no choices have to be made, but it's proven
usefull to at least:
\begin{itemize}
\item select a target (menu: ,,Embedded System'')
\item select the root filesystem type (menu: ,,Target Firmware type'')
\end{itemize}

Then quit saving changes. If you forgot that, just run \texttt{make} again, redo
your changes, then save.

\subsection{Building ADK}
Now that you have a (first) configuration, it is time to build the toolchain
(compiler, libraries) for cross-compiling. To do this, just enter {{{make}}}
again. The build starts downloading and compiling each needed part of the
toolchain, and later continues with building the first firmware image. Later
one can be taken as proof of a working ADK.

Already experienced in compiling gcc? Then you know... If not, better be told
that it takes \underline{really long} to finish. In the meantime I suggest reading the
next (optional) chapter dealing with internals about cross-compiling.

\section{Details Of Cross-Compiling}

TODO: someone with enough knowledge about this may fill this chapter with
\underline{interesting} information!

\section{Building A FreeWRT Firmware Image}

Ok. Your local copy of the FreeWRT ADK should now be prepared for building
images. The next step is to do an extensive configuration for the image you
want to create. To start the configuration menu, type {{{make menuconfig}}}.

when selecting packages, \texttt{<*>} means it will be inserted into the firmware
images and \texttt{<M>} means it will be build as an addon package which can be
installed later.

The target device and filesystem should already been chosen by you to the
right value, if not you will have to issue a \texttt{make clean} before actually
building the firmware image, because otherwise things get messed up. (smooth
rebuild is a (yet) missing feature in our buildroot.) For the packages, if
unsure, you can just select one of the package collections. After that, you
can still manually check the choices made by the collection and correct them
if appropriate. Do not forget to save your configuration when leaving!

Guess ... right, type \texttt{make} again to build the new FreeWRT firmware
image. Depending on your package selections and underlying hardware, this will
take different amounts of time. For your spare time there is the following
chapter giving some explanation about what is done at this point.

\section{Firmware Build Process In Detail}

Just like when building the ADK's toolchain, the sources for the selected
packages are downloaded from the internet first, then build using the
cross-compiler and libraries of the ADK.

TODO: more to follow by some more skilled people!!

\section{Troubleshooting}
This section deals with various tips for problems with ADK installation.

\subsection{Errors During Prerequisites Check}
To re-issue the checks, use ,,make prereq''.

\begin{itemize}
\item GNU make 3.80 too old
   On my FC4 buildsystem the first I get is
\begin{Verbatim}
   $ make
   GNU make 3.80 too old.
   Please install GNU make 3.81 or higher to continue.
   You can override this check, see http://www.freewrt.org/faq for details.
   It is suggested to upgrade your copy of bison to
   GNU Bison 2.3 because of its bug fixes.
   make: *** [.prereq_done] Error 1
\end{Verbatim}

   it is quite a nice error that tells me to use more up to date software, but we can
   anyhow give this hostsystem a try and tell make to ignore those errors/warnings:
\begin{Verbatim}
     make prereq-noerror
\end{Verbatim}
\end{itemize}