X-Git-Url: https://git.rohieb.name/openwrt.git/blobdiff_plain/204f28d64a545855532c72a0218cc84d67c74387..b40bc2899b2e399c07e4b0b1dda0f9cfcb9c8b5a:/docs/build.tex diff --git a/docs/build.tex b/docs/build.tex index ef58b0ba7..6828a2318 100644 --- a/docs/build.tex +++ b/docs/build.tex @@ -45,7 +45,7 @@ This article refers to the "Kamikaze" branch of OpenWrt, which can be downloaded subversion using the following command: \begin{Verbatim} -$ svn checkout https://svn.openwrt.org/openwrt/trunk kamikaze +$ svn checkout svn://svn.openwrt.org/openwrt/trunk kamikaze \end{Verbatim} Additionally, there is a trac interface on \href{https://dev.openwrt.org/}{https://dev.openwrt.org/} @@ -80,10 +80,10 @@ add a new version of one of the components above. \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} -$ svn checkout 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 @@ -91,15 +91,17 @@ 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} -$ 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} -$ ln -s packages/*/* kamikaze/package/ +$ make package/symlinks \end{Verbatim} \texttt{target} refers to the embedded platform, this contains items which are specific to @@ -180,7 +182,7 @@ and packages will be in the "\texttt{bin/packages}" directory. 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: +in OpenWrt you'll find several things: \begin{itemize} \item \texttt{package/\textit{}/Makefile} @@ -202,7 +204,6 @@ simplifies the entire ordeal. Here for example, is \texttt{package/bridge/Makefile}: \begin{Verbatim}[frame=single,numbers=left] -# $Id: Makefile 5624 2006-11-23 00:29:07Z nbd $ include $(TOPDIR)/rules.mk @@ -292,7 +293,7 @@ directly as the Nth argument to \texttt{BuildPackage}. \begin{itemize} \item \texttt{SECTION} \\ - The type of package (currently unused) + The section of package (currently unused) \item \texttt{CATEGORY} \\ Which menu it appears in menuconfig: Network, Sound, Utilities, Multimedia ... \item \texttt{TITLE} \\ @@ -305,6 +306,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{}. If defined as an external package, use \textit{+}. For a kernel version dependency use: \textit{@LINUX\_2\_} + \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{}/conffiles} (optional):} \\ @@ -382,6 +386,58 @@ After you have created your \texttt{package/\textit{}/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] + +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. @@ -393,7 +449,6 @@ For external kernel modules, you can add them to the build system just like if t Here for instance the Makefile for the I2C subsytem kernel modules : \begin{Verbatim}[frame=single,numbers=left] -# $Id $ I2CMENU:=I2C Bus @@ -481,3 +536,60 @@ Other useful targets include: \item \texttt{make package/\textit{}/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}