X-Git-Url: http://git.rohieb.name/openwrt.git/blobdiff_plain/6e2ed99ca37ae4140552fc24ce7b8bac9e156133..dda4e674cea767428ad1c9f5a50014bb38877a5d:/docs/build.tex

diff --git a/docs/build.tex b/docs/build.tex
index 54d31c582..493be127c 100644
--- a/docs/build.tex
+++ b/docs/build.tex
@@ -307,6 +307,9 @@ directly as the Nth argument to \texttt{BuildPackage}.
             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>}
+		\item \texttt{BUILDONLY} (optional) \\
+			Set this option to 1 if you do NOT want your package to appear in menuconfig.
+			This is useful for packages which are only used as build dependencies.
     \end{itemize}
 
 \textbf{\texttt{Package/\textit{<name>}/conffiles} (optional):} \\
@@ -384,6 +387,59 @@ 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.
 
+\subsection{Creating binary packages}
+
+You might want to create binary packages and include them in the resulting images as packages.
+To do so, you can use the following template, which basically sets to nothing the Configure and
+Compile templates.
+
+\begin{Verbatim}[frame=single,numbers=left]
+# $Id: $
+
+include $(TOPDIR)/rules.mk
+
+PKG_NAME:=binpkg
+PKG_VERSION:=1.0
+PKG_RELEASE:=1
+
+PKG_SOURCE:=binpkg-$(PKG_VERSION).tar.gz
+PKG_SOURCE_URL:=http://server
+PKG_MD5SUM:=9b7dc52656f5cbec846a7ba3299f73bd
+PKG_CAT:=zcat
+
+include $(INCLUDE_DIR)/package.mk
+
+define Package/binpkg
+  SECTION:=net
+  CATEGORY:=Network
+  TITLE:=Binary package
+endef
+
+define Package/bridge/description
+  Binary package
+endef
+
+define Build/Configure
+endef
+
+define Build/Compile
+endef
+
+define Package/bridge/install
+    $(INSTALL_DIR) $(1)/usr/sbin
+    $(INSTALL_BIN) $(PKG_BUILD_DIR)/* $(1)/usr/sbin/
+endef
+
+$(eval $(call BuildPackage,bridge))
+\end{Verbatim}
+
+Provided that the tarball which contains the binaries reflects the final
+directory layout (/usr, /lib ...), it becomes very easy to get your package
+look like one build from sources.
+
+Note that using the same technique, you can easily create binary pcakages
+for your proprietary kernel modules as well.
+
 \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.
@@ -483,3 +539,60 @@ Other useful targets include:
     \item \texttt{make package/\textit{<name>}/configure V=99}
 \end{itemize}
 
+
+\subsection{Using build environments}
+OpenWrt provides a means of building images for multiple configurations
+which can use multiple targets in one single checkout. These \emph{environments}
+store a copy of the .config file generated by \texttt{make menuconfig} and the contents
+of the \texttt{./files} folder.
+The script \texttt{./scripts/env} is used to manage these environments, it uses
+\texttt{git} (which needs to be installed on your system) as backend for version control.
+
+The command 
+\begin{Verbatim}
+  ./scripts/env help
+\end{Verbatim}
+produces a short help text with a list of commands.
+
+To create a new environment named \texttt{current}, run the following command
+\begin{Verbatim}
+  ./scripts/env new current
+\end{Verbatim}
+This will move your \texttt{.config} file and \texttt{./files} (if it exists) to
+the \texttt{env/} subdirectory and create symlinks in the base folder.
+
+After running make menuconfig or changing things in files/, your current state will
+differ from what has been saved before. To show these changes, use:
+\begin{Verbatim}
+  ./scripts/env diff
+\end{Verbatim}
+
+If you want to save these changes, run:
+\begin{Verbatim}
+  ./scripts/env save
+\end{Verbatim}
+If you want to revert your changes to the previously saved copy, run:
+\begin{Verbatim}
+  ./scripts/env revert
+\end{Verbatim}
+
+If you want, you can now create a second environment using the \texttt{new} command.
+It will ask you whether you want to make it a clone of the current environment (e.g.
+for minor changes) or if you want to start with a clean version (e.g. for selecting
+a new target).
+
+To switch to a different environment (e.g. \texttt{test1}), use:
+\begin{Verbatim}
+  ./scripts/env switch test1
+\end{Verbatim}
+
+To rename the current branch to a new name (e.g. \texttt{test2}), use:
+\begin{Verbatim}
+  ./scripts/env rename test2
+\end{Verbatim}
+
+If you want to get rid of environment switching and keep everything in the base directory
+again, use:
+\begin{Verbatim}
+  ./scripts/env clear
+\end{Verbatim}