openwrt5

2.1.2 Creating packages

2.1.2 创建数据包

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:

•   package//Makefile
• package//patches
• package//files

我们已经试图去做的一件有关OpenWrt's模板系统的事情就是使得运输软件到OpenWrt变得极为简单。如果你在OpenWrt中寻找一个典型的数据包目录，你会发现两种东西：

• package//Makefile
• package//patches
• package//files

The patches directory is optional and typically contains bug fixes or optimizations to reduce the size of the executable. The package makefile is the important item, provides the steps actually needed to download and compile the package.

这些补丁的目录是可选择的，通常都包括错误修复或优化以减小可执行文件的大小。该数据包生成文件是重要的项目，它提供了下载和编制这个数据包做需要的步骤。

The files directory is also optional and typicall contains package specific startup scripts or default configuration files that can be used out of the box with OpenWrt.

文件目录同样是可选的，通常包含特定的启动脚本数据包，或者可以在箱之外同OpenWrt一起使用的默认配置文件。

Looking at one of the package makefiles, you’d hardly recognize it as a makefile. Through what can only be described as blatant disregard and abuse of the traditional make format, the makefile has been transformed into an object oriented template which simplifies the entire ordeal.

找到其中一个数据包生成文件，你几乎不认为它是一个生成文件。通过对传统格式的不加理会的滥用，生成文件已经变成了一个目标导向的模板，它简化了整个复杂的过程。

Here for example, is package/bridge/Makefile:

例子就是，package/bridge/Makefile:

1  # $Id: Makefile 5624 2006-11-23 00:29:07Z nbd $
2  
3  include $(TOPDIR)/rules.mk
4  
5  PKG_NAME:=bridge
6  PKG_VERSION:=1.0.6
7  PKG_RELEASE:=1
8  
9  PKG_SOURCE:=bridge-utils-$(PKG_VERSION).tar.gz
10  PKG_SOURCE_URL:=@SF/bridge
11  PKG_MD5SUM:=9b7dc52656f5cbec846a7ba3299f73bd
12  PKG_CAT:=zcat
13  
14  PKG_BUILD_DIR:=$(BUILD_DIR)/bridge-utils-$(PKG_VERSION)
15  
16  include $(INCLUDE_DIR)/package.mk
17  
18  define Package/bridge
19    SECTION:=net
20    CATEGORY:=Base system
21    TITLE:=Ethernet bridging configuration utility
22    URL:=
23  endef
24  
25  define Package/bridge/description
26    Manage ethernet bridging:
27    a way to connect networks together to form a larger network.
28  endef
29  
30  define Build/Configure
31      $(call Build/Configure/Default, \
32          --with-linux-headers="$(LINUX_DIR)" \
33      )
34  endef
35  
36  define Package/bridge/install
37      $(INSTALL_DIR) $(1)/usr/sbin
38      $(INSTALL_BIN) $(PKG_BUILD_DIR)/brctl/brctl $(1)/usr/sbin/
39  endef
40  
41  $(eval $(call BuildPackage,bridge))

As you can see, there’s not much work to be done; everything is hidden in other makefiles and abstracted to the point where you only need to specify a few variables.

正如你所见的那样，没有多少工作需要做；所有一切都隐藏在另外的生成文件中，简单来说，你只需要指定一些变量。

• PKG_NAME
  The name of the package, as seen via menuconfig and ipkg

数据包的名字，通过menuconfig和ipkg查看

• PKG_VERSION
  The upstream version number that we are downloading

下载中的逆流版本数据

• PKG_RELEASE
  The version of this package Makefile

生成数据包的版本

• PKG_SOURCE
  The filename of the original sources

原始资源的文件名

• PKG_SOURCE_URL
  Where to download the sources from (no trailing slash), you can add multiple download sources by separating them with a
  and a carriage return.

从哪里下载资源（没有结尾的斜线），通过用回车分解它们你可以增加多重下载资源。

• PKG_MD5SUM
  A checksum to validate the download

验证下载的校验和

• PKG_CAT
  How to decompress the sources (zcat, bzcat, unzip)

怎样解压资源（zcat, bzcat, unzip）

• PKG_BUILD_DIR
  Where to compile the package

在哪里编制数据包

The PKG_* variables define where to download the package from; @SF is a special keyword for downloading packages from sourceforge. There is also another keyword of @GNU for grabbing GNU source releases. If any of the above mentionned download source fails, the OpenWrt mirrors will be used as source.

PKG_* 变量规定了到哪里去下载；@SF是从sourceforge下载数据包的一个特别的关键字。还有另外一个@GNU 关键字，用来抓取GNU资源释放。如果以上提到的任何一个下载资源失败，OpenWrt镜像就会被当做资源使用。

The md5sum (if present) is used to verify the package was downloaded correctly and PKG_BUILD_DIR defines where to find the package after the sources are uncompressed into $(BUILD_DIR).

md5sum （如果出现的话）是用来核实数据包被正确下载的，PKG_BUILD_DIR规定了数据解压进入$(BUILD_DIR)后到哪里去寻找数据包。

At the bottom of the file is where the real magic happens, "BuildPackage" is a macro set up by the earlier include statements. BuildPackage only takes one argument directly – the name of the package to be built, in this case "bridge". All other information is taken from the define blocks. This is a way of providing a level of verbosity, it’s inherently clear what the contents of the description template in Package/bridge is, which wouldn’t be the case if we passed this information directly as the Nth argument to BuildPackage.

文件底部是奇迹发生的地方，"BuildPackage" 是一个较早的包含程序指令建立的宏。BuildPackage只是直接采用了一个参数——要建造的数据包名称，在此情况下是"bridge"。所有其他的信息都来自于定义块。这种方式提供了冗长，它的本质清楚地说明：在Package/bridge 中的描述模板内容是什么，如果我们把此信息直接传输为BuildPackage的第N个参数，一切就完全不同了。

BuildPackage uses the following defines:

BuildPackage 使用如下定义：

Package/:
matches the argument passed to buildroot, this describes the package the menuconfig and ipkg entries. Within Package/ you can define the following variables:

与传输到工具链的参数相匹配，它描述了数据包、menuconfig、ipkg的进入。在Package/内部，你可以定义以下变量：

• SECTION
  The type of package (currently unused)

数据包的类型（当前未用）

• CATEGORY
  Which menu it appears in menuconfig: Network, Sound, Utilities, Multimedia ...

在menuconfig中它出现在哪个菜单：  网络，声音，公共工程，多媒体......

• TITLE
  A short description of the package

数据包的简短描述

• URL
  Where to find the original software

到哪里去寻找原始软件

• MAINTAINER (optional)
  Who to contact concerning the package

数据包的相关联系人

• DEPENDS (optional)
  Which packages must be built/installed before this package. To reference a dependency defined in the same Makefile, use . If defined as an external package, use +. For a kernel version dependency use: @LINUX_2_

在这个数据包之前，哪些数据包必须被建立/安装。参考在同一个生成文件中的附属，使用。如果被定义为一个外部数据包，使用+。对于一个内核版本附属，使用：@LINUX_2_

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

如果你不希望自己的数据包出现在menuconfig中，把这个选项设置到1。对于那些仅仅被用作建造附属的数据包来说这是很有用的。

Package//conffiles (optional):
A list of config files installed by this package, one file per line.

被此数据包安装的一个配置文件列表，每行一个文件。

Build/Prepare (optional):
A set of commands to unpack and patch the sources. You may safely leave this undefined.

解压和修补资源的一套命令。你可以不去定义。

Build/Configure (optional):
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 "$(call Build/Configure/Default,)" 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.

如果资源没有使用配置或者没有一个标准的配置脚本，你可以不去定义它，否则你可以把自己的命令放在这里，使用"$(call Build/Configure/Default,)"把额外的参数放入标准的配置参数中。第一列参数会像这样传递到配置脚本中：–arg 1 –arg 2。第二列包含那些应该在运行配置脚本之前就定义的参数，例如autoconf或者编制器确切变量。

To make it easier to modify the configure command line, you can either extend or completely override the following variables:

为了让修改配置命令行更加简单，你可以扩展或者完全覆盖如下变量：

• CONFIGURE_ARGS
  Contains all command line arguments (format: –arg 1 –arg 2)

包含所有命令行参数(format: –arg 1 –arg 2)

• CONFIGURE_VARS
  Contains all environment variables that are passed to ./configure (format: NAME="value")

包含所有传递到./configure的环境变量(format: NAME="value")

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

如何编制资源；大多数情况下你不用去定义。

As with Build/Configure there are two variables that allow you to override the make command line environment variables and flags:

因为 Build/Configure的存在，有两种变量允许你覆盖制作命令行环境参数和标志：

• MAKE_FLAGS
  Contains all command line arguments (typically variable overrides like NAME="value"

包含所有命令行参数（通常是可变的覆写，如NAME="value"

• MAKE_VARS
  Contains all environment variables that are passed to the make command

包含所有传递到制作命令的的环境变量

Build/InstallDev (optional):
If your package provides a library that needs to be made available to other packages, you can use the 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. $(1) points to the regular staging dir, typically staging_dir/ARCH , while $(2) points to 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 bin/ subdirectory is included in the PATH which is passed down to the build system processes.Please use $(1) and $(2) here instead of the build system variables $(STAGING_DIR) and $(STAGING_DIR_HOST), because the build system behavior when staging libraries might change in the future to include automatic uninstallation.

如果你的数据包提供了一个库，而这个库需要对于其他数据包可用，你可以使用Build/InstallDev 模板复制到分段目录中，这个分段目录被用来收集那些在创建期间其他数据包可能会用到的所有文件。当它被构建系统调用时，两个参数就会被传送到那里。 $(1) 指向连续分段运输的显示文件列表，通常是staging_dir/ARCH，而$(2)指向 staging_dir/host.主机分段运输的显示文件列表只作为二进制被使用，它们被执行或者链接到主机和它的bin/上，子目录包含于PATH中，PATH被传递到构建系统进程中。 在这里请使用 $(1) 和 $(2)，而不是构建系统变量$(STAGING_DIR) 和 $(STAGING_DIR_HOST)，因为当分段运输的库发生更改，以此包含自动卸载时，构建系统才会运行。

Package//install:
A set of commands to copy files out of the compiled source and into the ipkg which is represented by the $(1) directory. Note that there are currently 4 defined install macros:

用于从编制资源中复制出文件和复制文件到ipkg中一套命令,ipkg被表示为$(1)目录。注意这里当前有4个定义的安装宏：

 

• INSTALL_DIR
  install -d -m0755
• INSTALL_BIN
  install -m0755
• INSTALL_DATA
  install -m0644
• INSTALL_CONF
  install -m0600

The reason that some of the defines are prefixed by "Package/ " and others are simply "Build" is because of the possibility of generating multiple packages from a single source. OpenWrt works under the assumption of one source per package Makefile, but you can split that source into as many packages as desired. Since you only need to compile the sources once, there’s one global set of "Build" defines, but you can add as many "Package/" defines as you want by adding extra calls to BuildPackage – see the dropbear package for an example.

有些定义前缀有"Package/ " 而另外一些则是简单的"Build"，原因在于从单一资源生成多重数据包的可能性。OpenWrt是在假设每个数据包生成文件一个资源下工作的，但是你可以把资源分为你所希望得到的尽可能多的数据包。因为你只需要编制一次资源，有一个全球"Build"的固定定义，但是只要愿意，你就可以通过对BuildPackage增加额外的调用增加尽可能多的"Package/"定义——dropbear数据包就是个例子。

After you have created your package//Makefile, the new package will automatically show in the menu the next time you run "make menuconfig" and if selected will be built automatically the next time "make" is run.

当你创建了自己的数据包//生成文件，新的数据包就会在下次你运行"make menuconfig"时自动显示在菜单里，如果所选被自动构建，下次"make"就会运行。

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

OpenWrt的发布使得两种内核模块相互区别，这些内核模块和主线内核一同出现，其他的则可作为分离的项目。稍后我们会看到被这二者所用的一个公用模板。

For kernel modules that are part of the mainline kernel source, the makefiles are located in package/kernel/modules/*.mk and they appear under the section "Kernel modules"

对于那些作为主线内核资源一部分的内核模块，生成文件位于package/kernel/modules/*.mk，它们出现在"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 :

以下是the I2C subsytem内核模块生成文件的例子：

1  # $Id $
2  
3  I2CMENU:=I2C Bus
4  
5  define KernelPackage/i2c-core
6    TITLE:=I2C support
7    DESCRIPTION:=Kernel modules for i2c support
8    SUBMENU:=$(I2CMENU)
9    KCONFIG:=CONFIG_I2C_CORE CONFIG_I2C_DEV
10    FILES:=$(MODULES_DIR)/kernel/drivers/i2c/*.$(LINUX_KMOD_SUFFIX)
11    AUTOLOAD:=$(call AutoLoad,50,i2c-core i2c-dev)
12  endef
13  $(eval $(call KernelPackage,i2c-core))

To group kernel modules under a common description in menuconfig, you might want to define a MENU variable on top of the kernel modules makefile.

如果要把内核模块在一个menuconfig中的普通描述中聚集起来，你或许想在内核模块生成文件的顶端定义一个MENU 变量。

• TITLE
  The name of the module as seen via menuconfig

   通过menuconfig看到的模块名字

• DESCRIPTION
  The description as seen via help in menuconfig

   通过menuconfig中的帮助看到的说明

• SUBMENU
  The sub menu under which this package will be seen

  此副菜单下该数据包可见

• KCONFIG
  Kernel configuration option dependency. For external modules, remove it.

   内核配置选项附属。对于外部模块来说，删除它。

• FILES
  Files you want to inlude to this kernel module package, separate with spaces.

   你想要包含进这个内核模块数据包中的文件，和空间相分离。

• AUTOLOAD
  Modules that will be loaded automatically on boot, the order you write them is the order they would be loaded.

   会在引导上自动装载的模块，你写入它们的顺序就是装载它们的顺序。

After you have created your package/kernel/modules/.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 "make" is run.

创建好你自己的数据包/内核/模块 .mk后，在下次你运行"make menuconfig" 时新的内核模块数据包就会自动显示在"Kernel modules"之下的菜单中，如果选择了的话，会在下次运行"make" 时自动创建。