|
|
|
@ -1,20 +1,20 @@ |
|
|
|
|
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. |
|
|
|
|
Even if you did remember to install a compiler and every development tool offered, |
|
|
|
|
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 |
|
|
|
|
incompatible with the hardware on your development machine, so in a process called |
|
|
|
|
incompatible with the hardware on your development machine, so in a process called |
|
|
|
|
cross compiling you need to produce a new compiler capable of generating code for |
|
|
|
|
your embedded platform, and then use it to compile a basic Linux distribution to |
|
|
|
|
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 |
|
|
|
|
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 |
|
|
|
|
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, |
|
|
|
|
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, |
|
|
|
|
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. |
|
|
|
|
|
|
|
|
@ -22,17 +22,17 @@ changed to make the kernel run on the embedded platform. |
|
|
|
|
|
|
|
|
|
OpenWrt takes a different approach to building a firmware, downloading, patching |
|
|
|
|
and compiling everything from scratch, including the cross compiler. Or 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 |
|
|
|
|
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 |
|
|
|
|
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 |
|
|
|
|
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 |
|
|
|
|
copy of the existing kernel to see what changes had been made, the patches are |
|
|
|
|
already provided and the process ends up almost completely transparent. This doesn't |
|
|
|
|
a new firmware image -- there's no work to be done trying to track down an unmodified |
|
|
|
|
copy of the existing kernel to see what changes had been made, the patches are |
|
|
|
|
already provided and the process ends up almost completely transparent. This doesn't |
|
|
|
|
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. |
|
|
|
@ -58,14 +58,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 tools |
|
|
|
|
\item toolchain |
|
|
|
|
\item package |
|
|
|
|
\item 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 and the compiler and 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,13 +73,13 @@ 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. |
|
|
|
|
|
|
|
|
|
\texttt{package} is for exactly that -- packages. In an OpenWrt firmware, almost everything |
|
|
|
|
\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. |
|
|
|
|
|
|
|
|
|
\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}" |
|
|
|
|
directory which is broken down by platform and contains the kernel config and patches |
|
|
|
|
a specific embedded platform. Of particular interest here is the "\texttt{target/linux}" |
|
|
|
|
directory which is broken down by platform and contains the kernel config and patches |
|
|
|
|
to the kernel for a particular platform. There's also the "\texttt{target/image}" directory |
|
|
|
|
which describes how to package a firmware for a specific platform. |
|
|
|
|
|
|
|
|
@ -95,20 +95,20 @@ 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, |
|
|
|
|
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, |
|
|
|
|
\texttt{y/m/n} which are represented as follows: |
|
|
|
|
|
|
|
|
|
\begin{itemize} |
|
|
|
|
\item{\texttt{<*>} (pressing y)} \\ |
|
|
|
|
This will be included in the firmware image |
|
|
|
|
\item{\texttt{<M>} (pressing m)} \\ |
|
|
|
|
This will be compiled but not included (for later install) |
|
|
|
|
\item{\texttt{< >} (pressing n)} \\ |
|
|
|
|
This will not be compiled |
|
|
|
|
\item{\texttt{<*>} (pressing y)} \\ |
|
|
|
|
This will be included in the firmware image |
|
|
|
|
\item{\texttt{<M>} (pressing m)} \\ |
|
|
|
|
This will be compiled but not included (for later install) |
|
|
|
|
\item{\texttt{< >} (pressing n)} \\ |
|
|
|
|
This will not be compiled |
|
|
|
|
\end{itemize} |
|
|
|
|
|
|
|
|
|
After you've finished with the menu configuration, exit and when prompted, save your |
|
|
|
|
After you've finished with the menu configuration, exit and when prompted, save your |
|
|
|
|
configuration changes. To begin compiling the firmware, type "\texttt{make}". By default |
|
|
|
|
OpenWrt will only display a high level overview of the compile process and not each individual |
|
|
|
|
command. |
|
|
|
@ -126,10 +126,10 @@ make[4] -C target/utils prepare |
|
|
|
|
\end{Verbatim} |
|
|
|
|
|
|
|
|
|
This makes it easier to monitor which step it's actually compiling and reduces the amount |
|
|
|
|
of noise caused by the compile output. To see the full output, run the command |
|
|
|
|
of noise caused by the compile output. To see the full output, run the command |
|
|
|
|
"\texttt{make V=99}". |
|
|
|
|
|
|
|
|
|
During the build process, buildroot will download all sources to the "\texttt{dl}" |
|
|
|
|
During the build process, buildroot will download all sources to the "\texttt{dl}" |
|
|
|
|
directory and will start patching and compiling them in the "\texttt{build\_\textit{<arch>}}" |
|
|
|
|
directory. When finished, the resulting firmware will be in the "\texttt{bin}" directory |
|
|
|
|
and packages will be in the "\texttt{bin/packages}" directory. |
|
|
|
@ -143,8 +143,8 @@ incredibly easy to port software to OpenWrt. If you look at a typical package di |
|
|
|
|
in OpenWrt you'll find two things: |
|
|
|
|
|
|
|
|
|
\begin{itemize} |
|
|
|
|
\item \texttt{package/\textit{<name>}/Makefile} |
|
|
|
|
\item \texttt{package/\textit{<name>}/patches} |
|
|
|
|
\item \texttt{package/\textit{<name>}/Makefile} |
|
|
|
|
\item \texttt{package/\textit{<name>}/patches} |
|
|
|
|
\end{itemize} |
|
|
|
|
|
|
|
|
|
The patches directory is optional and typically contains bug fixes or optimizations to |
|
|
|
@ -193,9 +193,9 @@ define Build/Configure |
|
|
|
|
endef |
|
|
|
|
|
|
|
|
|
define Package/bridge/install |
|
|
|
|
install -m0755 -d $(1)/usr/sbin |
|
|
|
|
install -m0755 $(PKG_BUILD_DIR)/brctl/brctl \ |
|
|
|
|
$(1)/usr/sbin/ |
|
|
|
|
install -m0755 -d $(1)/usr/sbin |
|
|
|
|
install -m0755 $(PKG_BUILD_DIR)/brctl/brctl \ |
|
|
|
|
$(1)/usr/sbin/ |
|
|
|
|
endef |
|
|
|
|
|
|
|
|
|
$(eval $(call BuildPackage,bridge)) |
|
|
|
@ -206,32 +206,32 @@ As you can see, there's not much work to be done; everything is hidden in other |
|
|
|
|
and abstracted to the point where you only need to specify a few variables. |
|
|
|
|
|
|
|
|
|
\begin{itemize} |
|
|
|
|
\item \texttt{PKG\_NAME} \\ |
|
|
|
|
The name of the package, as seen via menuconfig and ipkg |
|
|
|
|
\item \texttt{PKG\_VERSION} \\ |
|
|
|
|
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} \\ |
|
|
|
|
Where to download the sources from |
|
|
|
|
\item \texttt{PKG\_MD5SUM} \\ |
|
|
|
|
A checksum to validate the download |
|
|
|
|
\item \texttt{PKG\_CAT} \\ |
|
|
|
|
How to decompress the sources (zcat, bzcat, unzip) |
|
|
|
|
\item \texttt{PKG\_NAME} \\ |
|
|
|
|
The name of the package, as seen via menuconfig and ipkg |
|
|
|
|
\item \texttt{PKG\_VERSION} \\ |
|
|
|
|
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} \\ |
|
|
|
|
Where to download the sources from |
|
|
|
|
\item \texttt{PKG\_MD5SUM} \\ |
|
|
|
|
A checksum to validate the download |
|
|
|
|
\item \texttt{PKG\_CAT} \\ |
|
|
|
|
How to decompress the sources (zcat, bzcat, unzip) |
|
|
|
|
\end{itemize} |
|
|
|
|
|
|
|
|
|
The \texttt{PKG\_*} variables define where to download the package from; |
|
|
|
|
\texttt{@SF} is a special keyword for downloading packages from sourceforge. |
|
|
|
|
\texttt{@SF} is a special keyword for downloading packages from sourceforge. |
|
|
|
|
The md5sum is used to verify the package was downloaded correctly and |
|
|
|
|
\texttt{PKG\_BUILD\_DIR} defines where to find the package after the sources are |
|
|
|
|
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 -- |
|
|
|
|
setup 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 |
|
|
|
@ -241,28 +241,28 @@ directly as the Nth argument to \texttt{BuildPackage}. |
|
|
|
|
\texttt{BuildPackage} uses the following defines: |
|
|
|
|
|
|
|
|
|
\textbf{\texttt{Package/\textit{<name>}}:} \\ |
|
|
|
|
\texttt{\textit{<name>}} matches the argument passed to buildroot, this describes |
|
|
|
|
the package the menuconfig and ipkg entries. Within \texttt{Package/\textit{<name>}} |
|
|
|
|
you can define the following variables: |
|
|
|
|
|
|
|
|
|
\begin{itemize} |
|
|
|
|
\item \texttt{SECTION} \\ |
|
|
|
|
The type of package (currently unused) |
|
|
|
|
\item \texttt{CATEGORY} \\ |
|
|
|
|
Which menu it appears in menuconfig |
|
|
|
|
\item \texttt{TITLE} \\ |
|
|
|
|
A short description of the package |
|
|
|
|
\item \texttt{URL} \\ |
|
|
|
|
Where to find the original software |
|
|
|
|
\item \texttt{MAINTAINER} (optional) \\ |
|
|
|
|
Who to contact concerning the package |
|
|
|
|
\item \texttt{DEPENDS} (optional) \\ |
|
|
|
|
Which packages must be built/installed before this package |
|
|
|
|
\end{itemize} |
|
|
|
|
\texttt{\textit{<name>}} matches the argument passed to buildroot, this describes |
|
|
|
|
the package the menuconfig and ipkg entries. Within \texttt{Package/\textit{<name>}} |
|
|
|
|
you can define the following variables: |
|
|
|
|
|
|
|
|
|
\begin{itemize} |
|
|
|
|
\item \texttt{SECTION} \\ |
|
|
|
|
The type of package (currently unused) |
|
|
|
|
\item \texttt{CATEGORY} \\ |
|
|
|
|
Which menu it appears in menuconfig |
|
|
|
|
\item \texttt{TITLE} \\ |
|
|
|
|
A short description of the package |
|
|
|
|
\item \texttt{URL} \\ |
|
|
|
|
Where to find the original software |
|
|
|
|
\item \texttt{MAINTAINER} (optional) \\ |
|
|
|
|
Who to contact concerning the package |
|
|
|
|
\item \texttt{DEPENDS} (optional) \\ |
|
|
|
|
Which packages must be built/installed before this package |
|
|
|
|
\end{itemize} |
|
|
|
|
|
|
|
|
|
\textbf{\texttt{Package/\textit{<name>}/conffiles} (optional):} \\ |
|
|
|
|
A list of config files installed by this package, one file per line. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
\textbf{\texttt{Build/Prepare} (optional):} \\ |
|
|
|
|
A set of commands to unpack and patch the sources. You may safely leave this |
|
|
|
|
undefined. |
|
|
|
@ -279,22 +279,22 @@ 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. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
|
|
|
|
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 |
|
|
|
|
desired. Since you only need to compile the sources once, there's one global set of |
|
|
|
|
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. |
|
|
|
|
|
|
|
|
|
After you've created your \texttt{package/\textit{<name>}/Makefile}, the new package |
|
|
|
|
After you've created your \texttt{package/\textit{<name>}/Makefile}, the new package |
|
|
|
|
will automatically show in the menu the next time you run "make menuconfig" and if selected |
|
|
|
|
will be built automatically the next time "\texttt{make}" is run. |
|
|
|
|
|
|
|
|
|
\subsubsection{Troubleshooting} |
|
|
|
|
|
|
|
|
|
If you find your package doesn't show up in menuconfig, try the following command to |
|
|
|
|
If you find your package doesn't show up in menuconfig, try the following command to |
|
|
|
|
see if you get the correct description: |
|
|
|
|
|
|
|
|
|
\begin{Verbatim} |
|
|
|
@ -306,15 +306,15 @@ shortcuts you can take. Instead of waiting for make to get to your package, you |
|
|
|
|
run one of the following: |
|
|
|
|
|
|
|
|
|
\begin{itemize} |
|
|
|
|
\item \texttt{make package/\textit{<name>}-clean V=99} |
|
|
|
|
\item \texttt{make package/\textit{<name>}-install V=99} |
|
|
|
|
\item \texttt{make package/\textit{<name>}-clean V=99} |
|
|
|
|
\item \texttt{make package/\textit{<name>}-install V=99} |
|
|
|
|
\end{itemize} |
|
|
|
|
|
|
|
|
|
Another nice trick is that if the source directory under \texttt{build\_\textit{<arch>}} |
|
|
|
|
is newer than the package directory, it won't clobber it by unpacking the sources again. |
|
|
|
|
If you were working on a patch you could simply edit the sources under the |
|
|
|
|
\texttt{build\_\textit{<arch>}/\textit{<source>}} directory and run the install command above, |
|
|
|
|
when satisfied, copy the patched sources elsewhere and diff them with the unpatched |
|
|
|
|
when satisfied, copy the patched sources elsewhere and diff them with the unpatched |
|
|
|
|
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. |
|
|
|
|
|
|
|
|
|