ar7: refresh patches

[openwrt.git] / docs / build.tex

diff --git a/docs/build.tex b/docs/build.tex
index 1335c81..54d31c5 100644 (file)
--- a/docs/build.tex
+++ b/docs/build.tex
@@ -39,17 +39,17 @@ 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}
+\subsubsection{Download OpenWrt}

 
 This article refers to the "Kamikaze" branch of OpenWrt, which can be downloaded via
 subversion using the following command:
 
 \begin{Verbatim}
 
 This article refers to the "Kamikaze" branch of OpenWrt, which can be downloaded via
 subversion using the following command:
 
 \begin{Verbatim}

-$ svn co https://svn.openwrt.org/openwrt/trunk kamikaze
+$ svn checkout https://svn.openwrt.org/openwrt/trunk kamikaze

 \end{Verbatim}
 
 \end{Verbatim}
 

-Additionally, ther is a trac interface on \href{https://dev.openwrt.org/}{https://dev.openwrt.org/}
-which can be used to monitor svn commits and browse the sources.
+Additionally, there is a trac interface on \href{https://dev.openwrt.org/}{https://dev.openwrt.org/}
+which can be used to monitor svn commits and browse the source repository.

 
 
 \subsubsection{The directory structure}
 
 
 \subsubsection{The directory structure}


@@ -65,25 +65,25 @@ There are four key directories in the base:
 
 \texttt{tools} and \texttt{toolchain} refer to common tools which will be
 used to build the firmware image, the compiler, and the C library.
 
 \texttt{tools} and \texttt{toolchain} refer to common tools which will be
 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>}}
+The result of this is three new directories, \texttt{build\_dir/host}, which is a temporary
+directory for building the target independent tools, \texttt{build\_dir/toolchain-\textit{<arch>}*}

 which is used for building the toolchain for a specific architecture, and
 which is used for building the toolchain for a specific architecture, and

-\texttt{staging\_dir\_\textit{<arch>}} where the resulting toolchain is installed.
+\texttt{staging\_dir/toolchain-\textit{<arch>}*} where the resulting toolchain is installed.

 You will not need to do anything with the toolchain directory unless you intend to
 add a new version of one of the components above.
 
 \begin{itemize}
 You will not 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>}}
+    \item \texttt{build\_dir/host}
+    \item \texttt{build\_dir/toolchain-\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. Note that packages are also maintained outside of the main
 \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. Note that packages are also maintained outside of the main

-trunk and can be obtained from subversion at the following location:
+trunk and can be obtained from subversion using the package feeds system:

 
 \begin{Verbatim}
 
 \begin{Verbatim}

-$ svn co https://svn.openwrt.org/openwrt/packages ../packages
+$ ./scripts/feeds update

 \end{Verbatim}
 
 Those packages can be used to extend the functionality of the build system and need to be
 \end{Verbatim}
 
 Those packages can be used to extend the functionality of the build system and need to be


@@ -91,30 +91,31 @@ symlinked into the main trunk. Once you do that, the packages will show up in th
 configuration. From kamikaze you would do something like this:
 
 \begin{Verbatim}
 configuration. From kamikaze you would do something like this:
 
 \begin{Verbatim}

-$ ls
-kamikaze  packages
-$ ln -s packages/net/nmap kamikaze/package/nmap
+$ ./scripts/feeds search nmap
+Search results in feed 'packages':
+nmap       Network exploration and/or security auditing utility
+
+$ ./scripts/feeds install nmap

 \end{Verbatim}
 
 To include all packages, issue the following command:
 
 \begin{Verbatim}
 \end{Verbatim}
 
 To include all packages, issue the following command:
 
 \begin{Verbatim}

-$ ln -s packages/*/* kamikaze/package/
+$ make package/symlinks

 \end{Verbatim}
 
 \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}"
 \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
-to the kernel for a particular platform. There's also the "\texttt{target/image}" directory
+directory which is broken down by platform \textit{<arch>} and contains the patches to the
+kernel, profile config, for a particular platform. There's also the "\texttt{target/image}" directory

 which describes how to package a firmware for a specific platform.
 
 which describes how to package a firmware for a specific platform.
 

-Both the target and package steps will use the directory "\texttt{build\_\textit{<arch>}}"
+Both the target and package steps will use the directory "\texttt{build\_dir/\textit{<arch>}}"

 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}
 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{build\_dir/\textit{<arch>}}

     \item \texttt{dl}
 \end{itemize}
 
     \item \texttt{dl}
 \end{itemize}
 


@@ -172,7 +173,7 @@ 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}"
 "\texttt{make V=99}".
 
 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 and will start patching and compiling them in the "\texttt{build\_dir/\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.
 
 directory. When finished, the resulting firmware will be in the "\texttt{bin}" directory
 and packages will be in the "\texttt{bin/packages}" directory.
 


@@ -186,7 +187,7 @@ in OpenWrt you'll find two things:
 \begin{itemize}
     \item \texttt{package/\textit{<name>}/Makefile}
     \item \texttt{package/\textit{<name>}/patches}
 \begin{itemize}
     \item \texttt{package/\textit{<name>}/Makefile}
     \item \texttt{package/\textit{<name>}/patches}

-       \item \texttt{package/\textit{<name>}/files}
+    \item \texttt{package/\textit{<name>}/files}

 \end{itemize}
 
 The patches directory is optional and typically contains bug fixes or optimizations to
 \end{itemize}
 
 The patches directory is optional and typically contains bug fixes or optimizations to


@@ -203,12 +204,6 @@ simplifies the entire ordeal.
 Here for example, is \texttt{package/bridge/Makefile}:
 
 \begin{Verbatim}[frame=single,numbers=left]
 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
 # $Id: Makefile 5624 2006-11-23 00:29:07Z nbd $
 
 include $(TOPDIR)/rules.mk


@@ -230,12 +225,14 @@ define Package/bridge
   SECTION:=net
   CATEGORY:=Base system
   TITLE:=Ethernet bridging configuration utility
   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
 
   URL:=http://bridge.sourceforge.net/
 endef
 

+define Package/bridge/description
+  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)" \
 define Build/Configure
     $(call Build/Configure/Default, \
         --with-linux-headers="$(LINUX_DIR)" \


@@ -307,7 +304,9 @@ directly as the Nth argument to \texttt{BuildPackage}.
         \item \texttt{MAINTAINER} (optional) \\
             Who to contact concerning the package
         \item \texttt{DEPENDS} (optional) \\
         \item \texttt{MAINTAINER} (optional) \\
             Who to contact concerning the package
         \item \texttt{DEPENDS} (optional) \\

-            Which packages must be built/installed before this package. To reference a dependency defined in the same Makefile, use \textit{<dependency name>}. If defined as an external package, use \textit{+<dependency name>}. For a kernel version dependency use: \textit{@LINUX\_2\_<minor version>}
+            Which packages must be built/installed before this package. To reference a dependency defined in the
+                       same Makefile, use \textit{<dependency name>}. If defined as an external package, use 
+                       \textit{+<dependency name>}. For a kernel version dependency use: \textit{@LINUX\_2\_<minor version>}

     \end{itemize}
 
 \textbf{\texttt{Package/\textit{<name>}/conffiles} (optional):} \\
     \end{itemize}
 
 \textbf{\texttt{Package/\textit{<name>}/conffiles} (optional):} \\


@@ -321,10 +320,42 @@ directly as the Nth argument to \texttt{BuildPackage}.
    You can leave this undefined if the source doesn't use configure or has a
    normal config script, otherwise you can put your own commands here or use
    "\texttt{\$(call Build/Configure/Default,\textit{<first list of arguments, second list>})}" as above to
    You can leave this undefined if the source doesn't use configure or has a
    normal config script, otherwise you can put your own commands here or use
    "\texttt{\$(call Build/Configure/Default,\textit{<first list of arguments, second list>})}" as above to

-   pass in additional arguments for a standard configure script. The first list of arguments will be passed to the configure script like that: $--arg 1$ $--arg 2$. The second list contains arguments that should be defined before running the configure script such as autoconf or compiler specific variables.
+   pass in additional arguments for a standard configure script. The first list of arguments will be passed
+   to the configure script like that: \texttt{--arg 1} \texttt{--arg 2}. The second list contains arguments that should be
+   defined before running the configure script such as autoconf or compiler specific variables.
+   
+   To make it easier to modify the configure command line, you can either extend or completely override the following variables:
+   \begin{itemize}
+     \item \texttt{CONFIGURE\_ARGS} \\
+            Contains all command line arguments (format: \texttt{--arg 1} \texttt{--arg 2})
+     \item \texttt{CONFIGURE\_VARS} \\
+            Contains all environment variables that are passed to ./configure (format: \texttt{NAME="value"})
+   \end{itemize}

 
 \textbf{\texttt{Build/Compile} (optional):} \\
    How to compile the source; in most cases you should leave this undefined.
 
 \textbf{\texttt{Build/Compile} (optional):} \\
    How to compile the source; in most cases you should leave this undefined.

+   
+   As with \texttt{Build/Configure} there are two variables that allow you to override
+   the make command line environment variables and flags:
+   \begin{itemize}
+     \item \texttt{MAKE\_FLAGS} \\
+          Contains all command line arguments (typically variable overrides like \texttt{NAME="value"}
+        \item \texttt{MAKE\_VARS} \\
+          Contains all environment variables that are passed to the make command
+   \end{itemize}
+
+\textbf{\texttt{Build/InstallDev} (optional):} \\
+       If your package provides a library that needs to be made available to other packages,
+       you can use the \texttt{Build/InstallDev} template to copy it into the staging directory
+       which is used to collect all files that other packages might depend on at build time.
+       When it is called by the build system, two parameters are passed to it. \texttt{\$(1)} points to
+       the regular staging dir, typically \texttt{staging\_dir/\textit{ARCH}}, while \texttt{\$(2)} points
+       to \texttt{staging\_dir/host}. The host staging dir is only used for binaries, which are
+       to be executed or linked against on the host and its \texttt{bin/} subdirectory is included
+       in the \texttt{PATH} which is passed down to the build system processes.
+       Please use \texttt{\$(1)} and \texttt{\$(2)} here instead of the build system variables
+       \texttt{\$(STAGING\_DIR)} and \texttt{\$(STAGING\_DIR\_HOST)}, because the build system behavior
+       when staging libraries might change in the future to include automatic uninstallation.

 
 \textbf{\texttt{Package/\textit{<name>}/install}:} \\
    A set of commands to copy files out of the compiled source and into the ipkg
 
 \textbf{\texttt{Package/\textit{<name>}/install}:} \\
    A set of commands to copy files out of the compiled source and into the ipkg


@@ -353,6 +384,52 @@ After you have created your \texttt{package/\textit{<name>}/Makefile}, the new p
 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.
 
 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.
 

+\subsection{Creating kernel modules packages}
+
+The OpenWrt distribution makes the distinction between two kind of kernel modules, those coming along with the mainline kernel, and the others available as a separate project. We will see later that a common template is used for both of them.
+
+For kernel modules that are part of the mainline kernel source, the makefiles are located in \textit{package/kernel/modules/*.mk} and they appear under the section "Kernel modules"
+
+For external kernel modules, you can add them to the build system just like if they were software packages by defining a KernelPackage section in the package makefile.
+
+Here for instance the Makefile for the I2C subsytem kernel modules :
+
+\begin{Verbatim}[frame=single,numbers=left]
+# $Id $
+
+I2CMENU:=I2C Bus
+
+define KernelPackage/i2c-core
+  TITLE:=I2C support
+  DESCRIPTION:=Kernel modules for i2c support
+  SUBMENU:=$(I2CMENU)
+  KCONFIG:=CONFIG_I2C_CORE CONFIG_I2C_DEV
+  FILES:=$(MODULES_DIR)/kernel/drivers/i2c/*.$(LINUX_KMOD_SUFFIX)
+  AUTOLOAD:=$(call AutoLoad,50,i2c-core i2c-dev)
+endef
+$(eval $(call KernelPackage,i2c-core))
+\end{Verbatim}
+
+To group kernel modules under a common description in menuconfig, you might want to define a \textit{<description>MENU} variable on top of the kernel modules makefile.
+
+\begin{itemize}
+    \item \texttt{TITLE} \\
+        The name of the module as seen via menuconfig
+    \item \texttt{DESCRIPTION} \\
+        The description as seen via help in menuconfig
+    \item \texttt{SUBMENU} \\
+        The sub menu under which this package will be seen
+    \item \texttt{KCONFIG} \\
+        Kernel configuration option dependency. For external modules, remove it.
+    \item \texttt{FILES} \\
+        Files you want to inlude to this kernel module package, separate with spaces.
+    \item \texttt{AUTOLOAD} \\
+        Modules that will be loaded automatically on boot, the order you write them is the order they would be loaded.
+\end{itemize}
+
+After you have created your \texttt{package/kernel/modules/\textit{<name>}.mk}, the new kernel modules package
+will automatically show in the menu under "Kernel modules" next time you run "make menuconfig" and if selected
+will be built automatically the next time "\texttt{make}" is run.

 
 \subsection{Conventions}
 
 
 \subsection{Conventions}
 


@@ -386,14 +463,14 @@ shortcuts you can take. Instead of waiting for make to get to your package, you
 run one of the following:
 
 \begin{itemize}
 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}
 
 \end{itemize}
 

-Another nice trick is that if the source directory under \texttt{build\_\textit{<arch>}}
+Another nice trick is that if the source directory under \texttt{build\_dir/\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
 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,
+\texttt{build\_dir/\textit{<arch>}/\textit{<source>}} directory and run the install command above,

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


@@ -401,8 +478,8 @@ it will remove the old sources and unpack a fresh copy.
 Other useful targets include:
 
 \begin{itemize}
 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}
+    \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}
 
 \end{itemize}