X-Git-Url: http://git.rohieb.name/openwrt.git/blobdiff_plain/0831b598d806a5cec1fe24b328504d3525eba85f..dfde60d8fc3570c0acdf24993fb5174a4dc80df4:/docs/buildroot-documentation.html
diff --git a/docs/buildroot-documentation.html b/docs/buildroot-documentation.html
index bd9642202..a577aae26 100644
--- a/docs/buildroot-documentation.html
+++ b/docs/buildroot-documentation.html
@@ -15,9 +15,9 @@
OpenWrt Buildroot
- Usage and documentation by Felix Fietkau, based on uClibc Buildroot
+
Usage and documentation by Felix Fietkau and Waldemar Brodkorb, based on uClibc Buildroot
documentation by Thomas Petazzoni. Contributions from Karsten Kruse,
- Ned Ludd, Martin Herren.
+ Ned Ludd, Martin Herren. OpenWrt Kernel Module Creation Howto by Markus Becker.
Last modification : $Id$
@@ -37,6 +37,14 @@
Location of downloaded packages
Extending OpenWrt with more Software
Ressources
+
+ About OpenWrt Kernel Module Compilation
+ Enable the kernel options
+ Create a buildroot option
+ Define the binary files for the kernel module
+ Specify the ipkg control file
+ Compile the kernel module
+
About OpenWrt Buildroot
@@ -88,10 +96,17 @@
Obtaining OpenWrt Buildroot
OpenWrt Buildroot is available via CVS - Concurrent Version System.
- For any kind of development you should get the latest version from cvs via:
+ For any kind of OpenWrt development you should get the latest version from cvs via:
$ cvs -d:pserver:anonymous@openwrt.org:/openwrt co openwrt
+ If you only like to create your own custom firmware images and pakages we
+ strongely suggest to use the CVS branch of the stable version (whiterussian):
+
+
+ $ cvs -d:pserver:anonymous@openwrt.org:/openwrt co -rwhiterussian openwrt
+
+
Using OpenWrt Buildroot
@@ -129,8 +144,8 @@
squashfs
jffs2 contains a writable root filesystem, which will expand to
- the size of your flash image. Note that you if you use the generic firmware
- Image, you need to pick the right image for your Flash size, because of different
+ the size of your flash image. Note: if you use the generic firmware image, you
+ need to pick the right image for your flash size, because of different
eraseblock sizes.
squashfs contains a read-only root filesystem using a modified
@@ -197,7 +212,7 @@
configuration, and the latter is used if you have selected
locale support.
-
Run the compilation again
+ Run the compilation again.
@@ -232,7 +247,9 @@
target (in the target directory) contains the
Makefiles and associated files for software related to the generation of
- the target root filesystem image. Two types of filesystems are supported
+ the target root filesystem image and the linux kernel for the different
+ system on a chip boards, used in the Wireless Routers.
+ Two types of filesystems are supported
: jffs2 and squashfs.
@@ -276,7 +293,7 @@
Create the target directory (build_ARCH/root/ by
default) and the target filesystem skeleton. This directory will contain
- the final root filesystem. To setup it up, it first deletes it, then it
+ the final root filesystem. To set it up, it first deletes it, then it
copies the skeleton available in target/default/target_skeleton
and then removes useless CVS/ directories.
@@ -302,10 +319,10 @@
For example, you may add the following to your
.bashrc (considering you're building for the MIPS
architecture and that Buildroot is located in
- ~/buildroot/) :
+ ~/openwrt/) :
-export PATH=$PATH:~/buildroot/staging_dir_mipsel/bin/
+export PATH=$PATH:~/openwrt/staging_dir_mipsel/bin/
Then you can simply do :
@@ -344,7 +361,7 @@ mipsel-linux-uclibc-gcc -o foo foo.c
downloaded by the Makefiles are all stored in the
DL_DIR which by default is the dl
directory. It's useful for example if you want to keep a complete
- version of Buildroot which is know to be working with the
+ version of Buildroot which is known to be working with the
associated tarballs. This will allow you to regenerate the
toolchain and the target filesystem with exactly the same
versions.
@@ -369,15 +386,39 @@ mipsel-linux-uclibc-gcc -o foo foo.c
config BR2_PACKAGE_FOO
- tristate "foo"
- default n
+ tristate "foo - some nice tool"
+ default m if CONFIG_DEVEL
help
This is a comment that explains what foo is.
+ If you depend on other software or library inside the Buildroot, it
+ is important that you automatically select these packages in your
+ Config.in. Example if foo depends on bar library:
+
+
+config BR2_PACKAGE_FOO
+ tristate "foo - some nice tool"
+ default m if CONFIG_DEVEL
+ select BR2_PACKAGE_LIBBAR
+ help
+ This is a comment that explains what foo is.
+
+
Of course, you can add other options to configure particular
things in your software.
+ Config.in in the package directory
+
+ To add your package to the configuration tool, you need
+ to add the following line to package/Config.in,
+ please add it to a section, which fits the purpose of foo:
+
+
+comment "Networking"
+source "package/foo/Config.in"
+
+
Makefile in the package directory
To add your package to the build process, you need to edit
@@ -391,18 +432,18 @@ package-$(BR2_PACKAGE_FOO) += foo
As you can see, this short line simply adds the target
foo to the list of targets handled by OpenWrt Buildroot.
-
- In addition to the default dependencies, you make your package
- depend on another package (e.g. a library) by adding a line:
+
In addition to the default dependencies, you make your package
+ depend on another package (e.g. a library) by adding a line:
foo-compile: bar-compile
- The .control file
+ The ipkg control file
Additionally, you need to create a control file which contains
information about your package, readable by the ipkg package
- utility.
+ utility. It should be created as file:
+ package/foo/ipkg/foo.control
The file looks like this
@@ -412,44 +453,45 @@ foo-compile: bar-compile
3 Section: net
4 Maintainer: Foo Software <foo@foosoftware.com>
5 Source: http://foosoftware.com
- 6 Description: Your Package Description
+ 6 Depends: libbar
+ 7 Description: Package Description
You can skip the usual Version: and Architecture
fields, as they will be generated by the make-ipkg-dir.sh script
- called from your Makefile
+ called from your Makefile. The Depends field is important, so that ipkg will
+ automatically fetch all dependend software on your target system.
The real Makefile
Finally, here's the hardest part. Create a file named
Makefile. It will contain the Makefile rules that
are in charge of downloading, configuring, compiling and installing
- the software. Below is an example that we will comment
- afterwards.
+ the software. Below is an example that we will comment afterwards.
1 # $Id$
- 2 include $(TOPDIR)/rules.mk
- 3 PKG_NAME:=foo
- 4 PKG_VERSION:=1.0
- 5 PKG_RELEASE:=1
- 6 PKG_MD5SUM:=4584f226523776a3cdd2fb6f8212ba8d
- 7
- 8 PKG_SOURCE:=$(PKG_NAME)-$(PKG_VERSION).tar.gz
- 9 PKG_SOURCE_URL:=http://www.foosoftware.org/downloads
- 10 PKG_DIR:=$(BUILD_DIR)/$(PKG_NAME)-$(PKG_VERSION)
- 11 PKG_IPK:=$(PACKAGE_DIR)/$(PKG_NAME)_$(PKG_VERSION)-$(PKG_RELEASE)_$(ARCH).ipk
- 12 PKG_IPK_DIR:=$(PKG_DIR)/ipkg
- 13
- 14 $(DL_DIR)/$(PKG_SOURCE):
- 15 $(SCRIPT_DIR)/download.pl $(DL_DIR) $(PKG_SOURCE) $(PKG_MD5SUM) $(PKG_SOURCE_URL)
+ 2
+ 3 include $(TOPDIR)/rules.mk
+ 4
+ 5 PKG_NAME:=foo
+ 6 PKG_VERSION:=1.0
+ 7 PKG_RELEASE:=1
+ 8 PKG_MD5SUM:=4584f226523776a3cdd2fb6f8212ba8d
+ 9
+ 10 PKG_SOURCE_URL:=http://www.foosoftware.org/downloads
+ 11 PKG_SOURCE:=$(PKG_NAME)-$(PKG_VERSION).tar.gz
+ 12 PKG_CAT:=zcat
+ 13
+ 14 PKG_BUILD_DIR:=$(BUILD_DIR)/$(PKG_NAME)-$(PKG_VERSION)
+ 15 PKG_INSTALL_DIR:=$(PKG_BUILD_DIR)/ipkg-install
16
- 17 $(PKG_DIR)/.source: $(DL_DIR)/$(PKG_SOURCE)
- 18 zcat $(DL_DIR)/$(PKG_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
- 19 touch $(PKG_DIR)/.source
+ 17 include $(TOPDIR)/package/rules.mk
+ 18
+ 19 $(eval $(call PKG_template,FOO,foo,$(PKG_VERSION)-$(PKG_RELEASE),$(ARCH)))
20
- 21 $(PKG_DIR)/.configured: $(PKG_DIR)/.source
- 22 (cd $(PKG_DIR); \
+ 21 $(PKG_BUILD_DIR)/.configured: $(PKG_BUILD_DIR)/.prepared
+ 22 (cd $(PKG_BUILD_DIR); \
23 $(TARGET_CONFIGURE_OPTS) \
24 CFLAGS="$(TARGET_CFLAGS)" \
25 ./configure \
@@ -458,36 +500,37 @@ foo-compile: bar-compile
28 --build=$(GNU_HOST_NAME) \
29 --prefix=/usr \
30 --sysconfdir=/etc \
- 31 );
- 32 touch $(PKG_DIR)/.configured;
- 33
- 34 $(PKG_DIR)/$(PKG_NAME): $(PKG_DIR)/.configured
- 35 $(MAKE) CC=$(TARGET_CC) -C $(PKG_DIR)
- 36
- 37 $(PKG_IPK): $(PKG_DIR)/$(PKG_NAME)
- 38 $(SCRIPT_DIR)/make-ipkg-dir.sh $(PKG_IPK_DIR) $(PKG_NAME).control $(PKG_VERSION)-$(PKG_RELEASE) $(ARCH)
- 39 $(MAKE) prefix=$(PKG_IPK_DIR)/usr -C $(PKG_DIR) install
- 40 rm -Rf $(PKG_IPK_DIR)/usr/man
- 41 $(IPKG_BUILD) $(PKG_IPK_DIR) $(PACKAGE_DIR)
- 42
- 43 $(IPKG_STATE_DIR)/info/$(PKG_NAME).list: $(PKG_IPK)
- 44 $(IPKG) install $(PKG_IPK)
- 45
- 46 prepare: $(PKG_DIR)/.source
- 47 compile: $(PKG_IPK)
- 48 install: $(IPKG_STATE_DIR)/info/$(PKG_NAME).list
- 49 clean:
- 50 rm -rf $(PKG_DIR)
- 51 rm -f $(PKG_IPK)
+ 31 --with-bar="$(STAGING_DIR)/usr" \
+ 32 );
+ 33 touch $@
+ 34
+ 35 $(PKG_BUILD_DIR)/.built:
+ 36 rm -rf $(PKG_INSTALL_DIR)
+ 37 mkdir -p $(PKG_INSTALL_DIR)
+ 38 $(MAKE) -C $(PKG_BUILD_DIR) \
+ 39 $(TARGET_CONFIGURE_OPTS) \
+ 40 install_prefix="$(PKG_INSTALL_DIR)" \
+ 41 all install
+ 42 touch $@
+ 43
+ 44 $(IPKG_FOO):
+ 46 install -d -m0755 $(IDIR_FOO)/usr/sbin
+ 47 cp -fpR $(PKG_INSTALL_DIR)/usr/sbin/foo $(IDIR_FOO)/usr/sbin
+ 49 $(RSTRIP) $(IDIR_FOO)
+ 50 $(IPKG_BUILD) $(IDIR_FOO) $(PACKAGE_DIR)
+ 51
+ 52 mostlyclean:
+ 53 make -C $(PKG_BUILD_DIR) clean
+ 54 rm $(PKG_BUILD_DIR)/.built
First of all, this Makefile example works for a single
binary software. For other software such as libraries or more
complex stuff with multiple binaries, it should be adapted. Look at
- the other Makefile files in the package
+ the other Makefile files in the package/
directory.
- At lines 3-12, a couple of useful variables are defined :
+ At lines 5-15, a couple of useful variables are defined:
PKG_NAME : The package name, e.g. foo.PKG_RELEASE : The release number that will be
- appended to the version number of your ipkg package.
-
- PKG_MD5SUM : The md5sum of the software archive.
+ appended to the version number of your ipkg package.PKG_SOURCE : The name of the tarball of
- your package on the download website of FTP site. As you can see
- PKG_NAME and PKG_VERSION are used.PKG_MD5SUM : The md5sum of the software archive.PKG_SOURCE_URL : Space separated list of the HTTP
or FTP sites from which the archive is downloaded. It must include the complete
path to the directory where FOO_SOURCE can be
found.PKG_DIR : The directory into which the software
+ PKG_SOURCE : The name of the tarball of
+ your package on the download website of FTP site. As you can see
+ PKG_NAME and PKG_VERSION are used.PKG_CAT : The tool needed for extraction of the
+ software archive.PKG_BUILD_DIR : The directory into which the software
will be configured and compiled. Basically, it's a subdirectory
- of BUILD_DIR which is created upon decompression of
+ of BUILD_DIR which is created upon extraction of
the tarball.PKG_IPK : The resulting ipkg package
+ PKG_INSTALL_DIR : The directory into the software
+ will be installed. It is a subdirectory of PKG_BUILD_DIR.
- Lines 14-15 defines a target that downloads the tarball from
- the remote site to the download directory
- (DL_DIR).
-
- Lines 17-19 defines a target and associated rules that
- uncompress the downloaded tarball. As you can see, this target
- depends on the tarball file, so that the previous target (line
- 14-15) is called before executing the rules of the current
- target. Uncompressing is followed by touching a hidden file
- to mark the software has having been uncompressed. This trick is
- used everywhere in Buildroot Makefile to split steps
- (download, uncompress, configure, compile, install) while still
- having correct dependencies.
-
- Lines 21-32 defines a target and associated rules that
+
In Line 3 and 17 we include common variables and routines to simplify
+ the process of ipkg creation. It includes routines to download, verify
+ and extract the software package archives.
+
+ Line 19 contains the magic line which automatically creates the
+ ipkg for us.
+
+ Lines 21-33 defines a target and associated rules that
configures the software. It depends on the previous target (the
- hidden .source file) so that we are sure the software has
+ hidden .prepared file) so that we are sure the software has
been uncompressed. In order to configure it, it basically runs the
well-known ./configurescript. As we may be doing
cross-compilation, target, host and
@@ -544,41 +584,21 @@ foo-compile: bar-compile
filesystem. Finally it creates a .configured file to
mark the software as configured.
- Lines 34-35 defines a target and a rule that compiles the
+
Lines 35-42 defines a target and a rule that compiles the
software. This target will create the binary file in the
compilation directory, and depends on the software being already
configured (hence the reference to the .configured
- file). It basically runs make inside the source
- directory.
-
- Lines 37-41 defines a target and associated rules that create
- the ipkg package which can optionally be embedded into
- the resulting firmware image. It depends on the binary file in
- the source directory, to make sure the software has been compiled.
- It uses the make-ipkg-dir.sh script, which will create the ipkg
- build directory for your package, copy your control file into
- that directory and add version and architecture information.
- Then it calls the install target of the
- software Makefile by passing a prefix
- argument, so that the Makefile doesn't try to install
- the software inside host /usr but inside target
- /usr. After the installation, the
- /usr/man directory inside the target filesystem is
- removed to save space.
+ file). Afterwards it installs the resulting binary into the
+ PKG_INSTALL_DIR. It basically runs
+ make install inside the source directory.
+
+ Lines 44-50 defines a target and associated rules that create
+ the ipkg package, which can optionally be embedded into
+ the resulting firmware image. It manually installs all files you
+ want to integrate in your resulting ipkg. RSTRIP will
+ recursevily strip all binaries and libraries.
Finally IPKG_BUILD is called to create the package.
- Line 43 and 44 define the installation target of your package,
- which will embed the software into the target filesystem.
-
- Lines 46-51 define the main targets that the Makefile in the
- package dir calls.
-
- prepare : Download and unpack the sourcecompile : Compile the source and create the packageinstall : Embed the package into the target filesystemclean : Remove all the files created by the build process
-
Conclusion
As you can see, adding a software to buildroot is simply a
@@ -587,13 +607,104 @@ foo-compile: bar-compile
the software.
If you package software that might be useful for other persons,
- don't forget to send a patch to OpenWrt developers !
+ don't forget to send a patch to OpenWrt developers!
+ Use the mail address: openwrt-devel@openwrt.org
+
Resources
- To learn more about OpenWrt Buildroot you can visit this
- website: http://openwrt.org/
+ To learn more about OpenWrt you can visit this website:
+ http://openwrt.org/
+
+
+
+
+
+
OpenWrt Kernel Module Creation Howto
+
+
+
About OpenWrt Kernel Module Compilation
+
+
You are planning to compile a kernel module? This howto will
+explain what you have to do, to have your kernel module installable as
+an ipkg.
+
+
Enable the kernel options
+
+
Enable the kernel options you want by modifying
+build_mipsel/linux/.config. We are assuming, that you already had your
+kernel compiled once here. You can do the modification by hand or by
+
+
+$ cd build_mipsel/linux
+$ make menuconfig
+
+
+And copy it, so your changes are not getting lost, when doing a 'make
+dirclean'. Here we assume that you are compiling for Broadcom chipset
+based devices:
+
+
$ cp .config ../../../target/linux/linux-2.4/config/brcm
+
+
+
Create a buildroot option
+
+
Create a buildroot option by modifying/inserting into
+target/linux/Config.in, e.g.
+
+
+config BR2_PACKAGE_KMOD_USB_KEYBOARD
+ tristate "Support for USB keyboards"
+ default m
+ depends BR2_PACKAGE_KMOD_USB_CONTROLLER
+
+
+
+
Define the binary files for the kernel module
+
+
Define the binary files for the kernel module by modifying/inserting into
+target/linux/linux-2.4/Makefile, e.g.
+
+$(eval $(call KMOD_template,USB_KEYBOARD,usb-kbd,\
+ $(MODULES_DIR)/kernel/drivers/input/input.o \
+ $(MODULES_DIR)/kernel/drivers/input/keybdev.o \
+ $(MODULES_DIR)/kernel/drivers/usb/usbkbd.o \
+,CONFIG_USB_KEYB,kmod-usb-core,60,input keybdev usbkbd))
+
+
+Where CONFIG_USB_KEYB is the kernel option, USB_KEYBOARD is the last
+part of BR2_PACKAGE_KMOD_USB_KEYBOARD and usb-kbd is part of the
+filename of the created ipkg.
+
+
Specify the ipkg control file
+
+
Create e.g. target/linux/control/kmod-usb-kbd.control with content similar to this:
+
+
+Package: kmod-usb-kbd
+Priority: optional
+Section: sys
+Maintainer: Markus Becker <mab@comnets.uni-bremen.de>
+Source: buildroot internal
+Description: Kernel Support for USB Keyboards
+
+
+
+
Compile the kernel module
+
+
Enable the kernel module with
+
+$ make menuconfig
+
+ in TOPDIR and selecting it.
+
+ Compile with
+
+$ make dirclean && make
+
+