X-Git-Url: https://git.rohieb.name/openwrt.git/blobdiff_plain/87021732394b57c922a035f315c29af4b001a58b..b4be80dea75f12a0385c3abcb6d1223dde792419:/openwrt/docs/buildroot-documentation.html diff --git a/openwrt/docs/buildroot-documentation.html b/openwrt/docs/buildroot-documentation.html index 91becd885..ede3796a6 100644 --- a/openwrt/docs/buildroot-documentation.html +++ b/openwrt/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

    @@ -80,17 +88,25 @@ gcc, binutils, uClibc and all the tools by hand. Of course, doing so is possible. But dealing with all configure options, with all problems of every gcc or binutils - version it very time-consuming and uninteresting. OpenWrt Buildroot automates this + version is very time-consuming and uninteresting. OpenWrt Buildroot automates this process through the use of Makefiles, and has a collection of patches for each gcc and binutils version to make them work - on the MIPS architecture of most Broadcom based Wireless Routers.

    + on the MIPS architecture of most Wireless Routers.

    Obtaining OpenWrt Buildroot

    -

    OpenWrt Buildroot is currently available as experimental snapshots

    - -

    The latest snapshot is always available at http://openwrt.org/downloads/experimental/, +

    OpenWrt Buildroot is available via CVS - Concurrent Version System. + 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

    @@ -128,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 @@ -140,25 +156,13 @@

    Customizing the target filesystem

    -

    There are two ways to customize the resulting target filesystem:

    - - +
  • You can customize the target filesystem skeleton, available under + package/base-files/default/. You can change + configuration files or other stuff here. However, the full file hierarchy + is not yet present, because it's created during the compilation process. + So you can't do everything on this target filesystem skeleton, but + changes to it remains even when you completely rebuild the cross-compilation + toolchain and the tools.

    Customizing the Busybox configuration

    @@ -196,7 +200,7 @@ configuration, and the latter is used if you have selected locale support.
    • -
  • Run the compilation again
    • +
  • Run the compilation again.
    • @@ -231,7 +235,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. @@ -264,18 +270,18 @@ is your architecture). This is where the cross compilation toolchain will be compiled.
    • -
  • Setup the staging directory (build_ARCH/staging_dir/ by +
  • Setup the staging directory (staging_dir_ARCH/ by default). This is where the cross-compilation toolchain will be installed. If you want to use the same cross-compilation toolchain for other purposes, such as compiling third-party applications, you can add - build_ARCH/staging_dir/bin to your PATH, and then use + staging_dir_ARCH/bin to your PATH, and then use arch-linux-gcc to compile your application. In order to setup this staging directory, it first removes it, and then it creates various subdirectories and symlinks inside it.
  • 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.
    • @@ -292,8 +298,8 @@ use the toolchain that was generated by the Buildroot.

    The toolchain generated by the Buildroot by default is located in - build_ARCH/staging_dir/. The simplest way to use it - is to add build_ARCH/staging_dir/bin/ to your PATH + staging_dir_ARCH. The simplest way to use it + is to add staging_dir_ARCH/bin/ to your PATH environment variable, and then to use arch-linux-gcc, arch-linux-objdump, arch-linux-ld, etc.

    @@ -301,10 +307,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/build_mipsel/staging_dir/bin/
+export PATH=$PATH:~/openwrt/staging_dir_mipsel/bin/

    Then you can simply do :

    @@ -324,9 +330,9 @@ mipsel-linux-uclibc-gcc -o foo foo.c uClibc toolchain outside of buildroot

    By default, the cross-compilation toolchain is generated inside - build_ARCH/staging_dir/. But sometimes, it may be useful to + staging_dir_ARCH/. But sometimes, it may be useful to install it somewhere else, so that it can be used to compile other programs - or by other users. Moving the build_ARCH/staging_dir/ + or by other users. Moving the staging_dir_ARCH/ directory elsewhere is not possible, because they are some hardcoded paths in the toolchain configuration.

    @@ -334,7 +340,7 @@ mipsel-linux-uclibc-gcc -o foo foo.c you can configure Buildroot to generate it elsewhere using the option of the configuration tool : Build options -> Toolchain and header file location, which defaults to - $(BUILD_DIR)/staging_dir/.

    + staging_dir_ARCH/.

    Location of downloaded packages

    @@ -343,7 +349,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.

    @@ -368,15 +374,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 @@ -390,18 +420,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

    @@ -411,81 +441,84 @@ 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  #############################################################
-     2  # foo
-     3  #############################################################
-     4  PKG_NAME:=foo
-     5  PKG_VERSION:=1.0
-     6  PKG_RELEASE:=1
-     7  PKG_SOURCE:=$(PKG_NAME)-$(PKG_VERSION).tar.gz
-     8  PKG_SITE:=http://www.foosoftware.org/downloads
-     9  PKG_DIR:=$(BUILD_DIR)/$(PKG_NAME)-$(PKG_VERSION)
-    10  PKG_IPK:=$(PACKAGE_DIR)/$(PKG_NAME)_$(PKG_VERSION)-$(PKG_RELEASE)_$(ARCH).ipk
-    11  PKG_IPK_DIR:=$(PKG_DIR)/ipkg
-    12
-    13  $(DL_DIR)/$(PKG_SOURCE):
-    14          $(WGET) -P $(DL_DIR) $(PKG_SITE)/$(PKG_SOURCE)
-    15
-    16  $(PKG_DIR)/.source: $(DL_DIR)/$(PKG_SOURCE)
-    17          zcat $(DL_DIR)/$(PKG_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
-    18          touch $(PKG_DIR)/.source
-    19
-    20  $(PKG_DIR)/.configured: $(PKG_DIR)/.source
-    21          (cd $(PKG_DIR); \
-    22                  $(TARGET_CONFIGURE_OPTS) \
-    23                  CFLAGS="$(TARGET_CFLAGS)" \
-    24                  ./configure \
-    25                  --target=$(GNU_TARGET_NAME) \
-    26                  --host=$(GNU_TARGET_NAME) \
-    27                  --build=$(GNU_HOST_NAME) \
-    28                  --prefix=/usr \
-    29                  --sysconfdir=/etc \
-    30          );
-    31          touch $(PKG_DIR)/.configured;
-    32
-    33  $(PKG_DIR)/foo $(PKG_DIR)/.configured
-    34          $(MAKE) CC=$(TARGET_CC) -C $(PKG_DIR)
-    35
-    36  $(PKG_IPK): $(PKG_DIR)/$(PKG_BINARY)
-    37		$(SCRIPT_DIR)/make-ipkg-dir.sh $(PKG_IPK_DIR) $(PKG_NAME).control $(PKG_VERSION)-$(PKG_RELEASE) $(ARCH)
-    38          $(MAKE) prefix=$(PKG_IPK_DIR)/usr -C $(PKG_DIR) install
-    39          rm -Rf $(PKG_IPK_DIR)/usr/man
-    40  	$(IPKG_BUILD) $(PKG_IPK_DIR) $(PACKAGE_DIR)
-    41
-    42  $(IPKG_STATE_DIR)/info/$(PKG_NAME).list: $(PKG_IPK)  
-    43  	$(IPKG) install $(PKG_IPK) 
-    44  
-    45  prepare: $(PKG_DIR)/.source
-    46  compile: $(PKG_IPK)
-    47  install: $(IPKG_STATE_DIR)/info/$(PKG_NAME).list
-    48  clean:
-    49  	rm -rf $(PKG_DIR)
-    50		rm -f $(PKG_IPK)
+     1  # $Id$
+     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	include $(TOPDIR)/package/rules.mk
+    18
+    19	$(eval $(call PKG_template,FOO,foo,$(PKG_VERSION)-$(PKG_RELEASE),$(ARCH)))
+    20
+    21  $(PKG_BUILD_DIR)/.configured:
+    22          (cd $(PKG_BUILD_DIR); \
+    23                  $(TARGET_CONFIGURE_OPTS) \
+    24                  CFLAGS="$(TARGET_CFLAGS)" \
+    25                  ./configure \
+    26                  --target=$(GNU_TARGET_NAME) \
+    27                  --host=$(GNU_TARGET_NAME) \
+    28                  --build=$(GNU_HOST_NAME) \
+    29                  --prefix=/usr \
+    30                  --sysconfdir=/etc \
+    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 4-11, a couple of useful variables are defined :

    +

    At lines 5-15, a couple of useful variables are defined:

    -

    Lines 13-14 defines a target that downloads the tarball from - the remote site to the download directory - (DL_DIR).

    - -

    Lines 16-18 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 - 13-14) 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 20-31 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 @@ -540,41 +572,31 @@ foo-compile: bar-compile filesystem. Finally it creates a .configured file to mark the software as configured.

    -

    Lines 33-34 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 36-40 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 42 and 43 define the installation target of your package, - which will embed the software into the target filesystem.

    - -

    Lines 45-50 define the main targets that the Makefile in the - package dir calls. -

    - +

    If you want other targets to be executed at compile, + install or clean time (e.g. for installing + a library into the staging dir), just create the targets (usually + install-dev and uninstall-dev) and enable + them like this: +

    +compile-targets: install-dev
+clean-targets: uninstall-dev
+
    +

    Conclusion

    As you can see, adding a software to buildroot is simply a @@ -583,13 +605,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
+
    +

    +
    +