mirror of
git://projects.qi-hardware.com/openwrt-xburst.git
synced 2024-12-24 05:11:46 +02:00
some more build system documentation
git-svn-id: svn://svn.openwrt.org/openwrt/trunk@5646 3c298f89-4303-0410-b956-a3cf2f4a3e73
This commit is contained in:
parent
1967751704
commit
5b49978c7d
127
docs/build.tex
127
docs/build.tex
@ -1,5 +1,5 @@
|
||||
One of the biggest challenges to getting started with embedded devices is that you
|
||||
just can't install a copy of Linux and expect to be able to compile a firmware.
|
||||
can't just install a copy of Linux and expect to be able to compile a firmware.
|
||||
Even if you did remember to install a compiler and every development tool offered,
|
||||
you still wouldn't have the basic set of tools needed to produce a firmware image.
|
||||
The embedded device represents an entirely new hardware platform, which is
|
||||
@ -9,25 +9,24 @@ your embedded platform, and then use it to compile a basic Linux distribution to
|
||||
run on your device.
|
||||
|
||||
The process of creating a cross compiler can be tricky, it's not something that's
|
||||
regularly attempted and so the there's a certain amount of mystery and black magic
|
||||
regularly attempted and so there's a certain amount of mystery and black magic
|
||||
associated with it. In many cases when you're dealing with embedded devices you'll
|
||||
be provided with a binary copy of a compiler and basic libraries rather than
|
||||
instructions for creating your own -- it's a time saving step but at the same time
|
||||
often means you'll be using a rather dated set. Likewise, it's also common to be
|
||||
provided with a patched copy of the Linux kernel from the board or chip vendor,
|
||||
often means you'll be using a rather dated set of tools. Likewise, it's also common
|
||||
to be provided with a patched copy of the Linux kernel from the board or chip vendor,
|
||||
but this is also dated and it can be difficult to spot exactly what has been
|
||||
changed to make the kernel run on the embedded platform.
|
||||
modified to make the kernel run on the embedded platform.
|
||||
|
||||
\subsection{Building an image}
|
||||
|
||||
OpenWrt takes a different approach to building a firmware, downloading, patching
|
||||
and compiling everything from scratch, including the cross compiler. Or to put it
|
||||
OpenWrt takes a different approach to building a firmware; downloading, patching
|
||||
and compiling everything from scratch, including the cross compiler. To put it
|
||||
in simpler terms, OpenWrt doesn't contain any executables or even sources, it's an
|
||||
automated system for downloading the sources, patching them to work with the given
|
||||
platform and compiling them correctly for the platform. What this means is that
|
||||
platform and compiling them correctly for that platform. What this means is that
|
||||
just by changing the template, you can change any step in the process.
|
||||
|
||||
|
||||
As an example, if a new kernel is released, a simple change to one of the Makefiles
|
||||
will download the latest kernel, patch it to run on the embedded platform and produce
|
||||
a new firmware image -- there's no work to be done trying to track down an unmodified
|
||||
@ -37,7 +36,7 @@ just apply to the kernel, but to anything included with OpenWrt -- It's this one
|
||||
simple understated concept which is what allows OpenWrt to stay on the bleeding edge
|
||||
with the latest compilers, latest kernels and latest applications.
|
||||
|
||||
So let's take a look at OpenWrt and see how this all works
|
||||
So let's take a look at OpenWrt and see how this all works.
|
||||
|
||||
|
||||
\subsubsection{Download openwrt}
|
||||
@ -46,7 +45,7 @@ This article refers to the "Kamikaze" branch of OpenWrt, which can be downloaded
|
||||
subversion using the following command:
|
||||
|
||||
\begin{Verbatim}
|
||||
svn co https://svn.openwrt.org/openwrt/trunk kamikaze
|
||||
$ svn co https://svn.openwrt.org/openwrt/trunk kamikaze
|
||||
\end{Verbatim}
|
||||
|
||||
Additionally, there's a trac interface on \href{https://dev.openwrt.org/}{https://dev.openwrt.org/}
|
||||
@ -58,14 +57,14 @@ which can be used to monitor svn commits and browse the sources.
|
||||
There are four key directories in the base:
|
||||
|
||||
\begin{itemize}
|
||||
\item tools
|
||||
\item toolchain
|
||||
\item package
|
||||
\item target
|
||||
\item \texttt{tools}
|
||||
\item \texttt{toolchain}
|
||||
\item \texttt{package}
|
||||
\item \texttt{target}
|
||||
\end{itemize}
|
||||
|
||||
\texttt{tools} and \texttt{toolchain} refer to common tools which will be
|
||||
used to build the firmware image and the compiler and c library.
|
||||
used to build the firmware image, the compiler, and the c library.
|
||||
The result of this is three new directories, \texttt{tool\_build}, which is a temporary
|
||||
directory for building the target independent tools, \texttt{toolchain\_build\_\textit{<arch>}}
|
||||
which is used for building the toolchain for a specific architecture, and
|
||||
@ -73,9 +72,29 @@ which is used for building the toolchain for a specific architecture, and
|
||||
You won't need to do anything with the toolchain directory unless you intend to
|
||||
add a new version of one of the components above.
|
||||
|
||||
\begin{itemize}
|
||||
\item \texttt{tool\_build}
|
||||
\item \texttt{toolchain\_build\_\textit{<arch>}}
|
||||
\end{itemize}
|
||||
|
||||
\texttt{package} is for exactly that -- packages. In an OpenWrt firmware, almost everything
|
||||
is an \texttt{.ipk}, a software package which can be added to the firmware to provide new
|
||||
features or removed to save space.
|
||||
features or removed to save space. Note that packages are also maintained outside of the main
|
||||
trunk and can be obtained from subversion at the following location:
|
||||
|
||||
\begin{Verbatim}
|
||||
$ svn co https://svn.openwrt.org/openwrt/packages ../packages
|
||||
\end{Verbatim}
|
||||
|
||||
Those packages can be used to extend the functionality of the build system and need to be
|
||||
symlinked into the main trunk. Once you do that, the packages will show up in the menu for
|
||||
configuration. From kamikaze you would do something like this:
|
||||
|
||||
\begin{Verbatim}
|
||||
$ ls
|
||||
kamikaze packages
|
||||
$ ln -s packages/net/nmap kamikaze/package/nmap
|
||||
\end{Verbatim}
|
||||
|
||||
\texttt{target} refers to the embedded platform, this contains items which are specific to
|
||||
a specific embedded platform. Of particular interest here is the "\texttt{target/linux}"
|
||||
@ -87,6 +106,10 @@ Both the target and package steps will use the directory "\texttt{build\_\textit
|
||||
as a temporary directory for compiling. Additionally, anything downloaded by the toolchain,
|
||||
target or package steps will be placed in the "\texttt{dl}" directory.
|
||||
|
||||
\begin{itemize}
|
||||
\item \texttt{build\_\textit{<arch>}}
|
||||
\item \texttt{dl}
|
||||
\end{itemize}
|
||||
|
||||
\subsubsection{Building OpenWrt}
|
||||
|
||||
@ -96,7 +119,11 @@ simple enough that an inexperienced end user can easily build his or her own cus
|
||||
Running the command "\texttt{make menuconfig}" will bring up OpenWrt's configuration menu
|
||||
screen, through this menu you can select which platform you're targeting, which versions of
|
||||
the toolchain you want to use to build and what packages you want to install into the
|
||||
firmware image. Similar to the linux kernel config, almost every option has three choices,
|
||||
firmware image. Note that it will also check to make sure you have the basic dependencies for it
|
||||
to run correctly. If that fails, you will need to install some more tools in your local environment
|
||||
before you can begin.
|
||||
|
||||
Similar to the linux kernel config, almost every option has three choices,
|
||||
\texttt{y/m/n} which are represented as follows:
|
||||
|
||||
\begin{itemize}
|
||||
@ -137,7 +164,6 @@ and packages will be in the "\texttt{bin/packages}" directory.
|
||||
|
||||
\subsection{Creating packages}
|
||||
|
||||
|
||||
One of the things that we've attempted to do with OpenWrt's template system is make it
|
||||
incredibly easy to port software to OpenWrt. If you look at a typical package directory
|
||||
in OpenWrt you'll find two things:
|
||||
@ -159,49 +185,53 @@ simplifies the entire ordeal.
|
||||
Here for example, is \texttt{package/bridge/Makefile}:
|
||||
|
||||
\begin{Verbatim}[frame=single,numbers=left]
|
||||
#
|
||||
# Copyright (C) 2006 OpenWrt.org
|
||||
#
|
||||
# This is free software, licensed under the GNU General Public License v2.
|
||||
# See /LICENSE for more information.
|
||||
#
|
||||
# $Id: Makefile 5624 2006-11-23 00:29:07Z nbd $
|
||||
|
||||
include $(TOPDIR)/rules.mk
|
||||
|
||||
PKG_NAME:=bridge
|
||||
PKG_VERSION:=1.0.6
|
||||
PKG_RELEASE:=1
|
||||
|
||||
PKG_BUILD_DIR:=$(BUILD_DIR)/bridge-utils-$(PKG_VERSION)
|
||||
PKG_SOURCE:=bridge-utils-$(PKG_VERSION).tar.gz
|
||||
PKG_SOURCE_URL:=@SF/bridge
|
||||
PKG_MD5SUM:=9b7dc52656f5cbec846a7ba3299f73bd
|
||||
PKG_CAT:=zcat
|
||||
|
||||
PKG_BUILD_DIR:=$(BUILD_DIR)/bridge-utils-$(PKG_VERSION)
|
||||
|
||||
include $(INCLUDE_DIR)/package.mk
|
||||
|
||||
define Package/bridge
|
||||
SECTION:=base
|
||||
CATEGORY:=Network
|
||||
DEFAULT:=y
|
||||
SECTION:=net
|
||||
CATEGORY:=Base system
|
||||
TITLE:=Ethernet bridging configuration utility
|
||||
DESCRIPTION:=\
|
||||
Manage ethernet bridging: a way to connect networks together to \\\
|
||||
form a larger network.
|
||||
URL:=http://bridge.sourceforge.net/
|
||||
endef
|
||||
|
||||
define Package/bridge/description
|
||||
Ethernet bridging configuration utility
|
||||
Manage ethernet bridging; a way to connect networks together
|
||||
to form a larger network.
|
||||
endef
|
||||
|
||||
define Build/Configure
|
||||
$(call Build/Configure/Default, \
|
||||
--with-linux-headers=$(LINUX_DIR))
|
||||
$(call Build/Configure/Default, \
|
||||
--with-linux-headers="$(LINUX_DIR)" \
|
||||
)
|
||||
endef
|
||||
|
||||
define Package/bridge/install
|
||||
install -m0755 -d $(1)/usr/sbin
|
||||
install -m0755 $(PKG_BUILD_DIR)/brctl/brctl \
|
||||
$(1)/usr/sbin/
|
||||
$(INSTALL_DIR) $(1)/usr/sbin
|
||||
$(INSTALL_BIN) $(PKG_BUILD_DIR)/brctl/brctl $(1)/usr/sbin/
|
||||
endef
|
||||
|
||||
$(eval $(call BuildPackage,bridge))
|
||||
\end{Verbatim}
|
||||
|
||||
|
||||
As you can see, there's not much work to be done; everything is hidden in other makefiles
|
||||
and abstracted to the point where you only need to specify a few variables.
|
||||
|
||||
@ -212,8 +242,6 @@ and abstracted to the point where you only need to specify a few variables.
|
||||
The upstream version number that we're downloading
|
||||
\item \texttt{PKG\_RELEASE} \\
|
||||
The version of this package Makefile
|
||||
\item \texttt{PKG\_BUILD\_DIR} \\
|
||||
Where to compile the package
|
||||
\item \texttt{PKG\_SOURCE} \\
|
||||
The filename of the original sources
|
||||
\item \texttt{PKG\_SOURCE\_URL} \\
|
||||
@ -222,6 +250,8 @@ and abstracted to the point where you only need to specify a few variables.
|
||||
A checksum to validate the download
|
||||
\item \texttt{PKG\_CAT} \\
|
||||
How to decompress the sources (zcat, bzcat, unzip)
|
||||
\item \texttt{PKG\_BUILD\_DIR} \\
|
||||
Where to compile the package
|
||||
\end{itemize}
|
||||
|
||||
The \texttt{PKG\_*} variables define where to download the package from;
|
||||
@ -231,7 +261,7 @@ The md5sum is used to verify the package was downloaded correctly and
|
||||
uncompressed into \texttt{\$(BUILD\_DIR)}.
|
||||
|
||||
At the bottom of the file is where the real magic happens, "BuildPackage" is a macro
|
||||
setup by the earlier include statements. BuildPackage only takes one argument directly --
|
||||
set up by the earlier include statements. BuildPackage only takes one argument directly --
|
||||
the name of the package to be built, in this case "\texttt{bridge}". All other information
|
||||
is taken from the define blocks. This is a way of providing a level of verbosity, it's
|
||||
inherently clear what the contents of the \texttt{description} template in
|
||||
@ -278,12 +308,21 @@ directly as the Nth argument to \texttt{BuildPackage}.
|
||||
|
||||
\textbf{\texttt{Package/\textit{<name>}/install}:} \\
|
||||
A set of commands to copy files out of the compiled source and into the ipkg
|
||||
which is represented by the \texttt{\$(1)} directory.
|
||||
which is represented by the \texttt{\$(1)} directory. Note that there are currently
|
||||
3 defined install macros:
|
||||
\begin{itemize}
|
||||
\item \texttt{INSTALL\_DIR} \\
|
||||
install -d -m0755
|
||||
\item \texttt{INSTALL\_BIN} \\
|
||||
install -m0755
|
||||
\item \texttt{INSTALL\_DATA} \\
|
||||
install -m0644
|
||||
\end{itemize}
|
||||
|
||||
The reason that some of the defines are prefixed by "\texttt{Package/\textit{<name>}}"
|
||||
and others are simply "\texttt{Build}" is because of the possibility of generating
|
||||
multiple packages from a single source. OpenWrt works under the assumption of one
|
||||
source per package makefile, but you can split that source into as many packages as
|
||||
source per package Makefile, but you can split that source into as many packages as
|
||||
desired. Since you only need to compile the sources once, there's one global set of
|
||||
"\texttt{Build}" defines, but you can add as many "Package/<name>" defines as you want
|
||||
by adding extra calls to \texttt{BuildPackage} -- see the dropbear package for an example.
|
||||
@ -318,3 +357,11 @@ when satisfied, copy the patched sources elsewhere and diff them with the unpatc
|
||||
sources. A warning though - if you go modify anything under \texttt{package/\textit{<name>}}
|
||||
it will remove the old sources and unpack a fresh copy.
|
||||
|
||||
Other useful targets include:
|
||||
|
||||
\begin{itemize}
|
||||
\item \texttt{make package/\textit{<name>}-prepare V=99}
|
||||
\item \texttt{make package/\textit{<name>}-compile V=99}
|
||||
\item \texttt{make package/\textit{<name>}-configure V=99}
|
||||
\end{itemize}
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user