Adding a new package(GeeXbox)(En&zh_TW)

What is a package(何謂套件)

A package can be described as a component of the GeeXboX distribution. It can be represented by a library, a driver or even by software. It consists of a set of shell scripts that are used by the GeeXboX toolchain to build the program, eventually after being patched and add it to the generated ISO file. The GeeXboX toolchain supports packages dependencies meaning that you can define requirements before doing some actions to your package. Each new package has to be put in the packages/ directory of the sources.

一個套件可以描述為 GeeXboX 發佈的一個組成，它可以是一個函式庫，一個驅動程式，或甚至是一個軟體。

它包含一組 Shell Scripts，它們在 GeeXboX 工具集中用來建立程式，加上補丁等，並將之加入最後產生的 ISO 檔。

GeeXboX 工具集支援套件相依性，意即你可以定義你的套件動作之前的某些要求，每個新套件必須放在 GeeXboX 源碼裡的 packages/目錄下。

Package definition files(套件定義檔)

Here is a short list of available package definition files that can be used with the GeeXboX toolchain :

- unpack : the list of actions to be done when unpacking the package archive. It generally consists of editing some configuration files. This file is optional.

- build : the list of actions to be done for building the package from sources. It usually consists of doing a ./configure && make with the good build arguments.

- install : the list of actions to be done when adding the built files to the ISO. It usually simply consists of copying the binary and configuration files to their right location in ISO.

Please note that each of these files have to be executable in order to be processed.

Each time one of these scripts is executed and ends up with success, a file is created in build.arch/.stamps/package/ That way, if this file exists and another script call for it, the actions won't be executed twice.

Each package script can also be executed manually for test purpose doing :

./scripts/{get|unpack|build|install} package 

Another required file is the url file, which is a simple text file containing the HTTP/FTP locations of files to be downloaded to build the package.

A package can also contains the following directories :

- config : where the package configuration files are placed.

- init.d : all files from this dir will be automatically copied to /etc/init.d on ISO and will be automatically launched at boot. These files need to have the executable flag.

- patches : all files in this dir will be applied as patch on the sources at unpack time. Theses files need to be unified patches, generated diff -Naur.

If multiple files are present, be sure that they can apply one over another.

- src : this directory may contain C source code that will be compiled at build time.

底下是可用的套件定義檔簡單列表，它們用在 GeeXboX 工具集中：

- unpack : 動作列表，在解開套件案卷時叫用，一般由編輯某些組態檔組成，這個檔案是選擇性的。

- build : 動作列表，從源碼建立套件時叫用。通常由設定好的參數叫用 ./configure && make 完成。

- install : 動作列表，用於將建立出來的檔案加入 ISO 檔中。通常簡單的由複製執行檔、組態檔到 ISO 檔中正確位置組成。

請注意上面每個檔都必須具備執行權以便叫用。

每次這些 scripts 中任何一個執行並成功結束時，會產生一個相同名稱的檔在 build.arch/.stamps/package/SAME_FILE_NAME，例如 build.i386/.stamps/busybox/unpack 。這種方式是用來避免二次呼叫。

每個套件 script 也能為了測試方便手動執行：

./scripts/{get|unpack|build|install} package 

另一個必要的檔是 url 檔，它是簡單的純文字檔，指出用來建立套件源碼的 HTTP/FTP 下載點位置。

一個套件也能包含下列目錄：

- config : 建立套件時用得到的組態檔。

- init.d : 此目錄下的所有檔將自動複製到 ISO 檔中的 /etc/init.d，以便開機時自動叫用。當然這些檔需要具備執行權。

- patches : 此目錄下所有檔將用於對源碼在 解壓縮(unpack) 時作補丁動作。所有這些檔是針對那些需要統一補丁的源碼以 diff -Naur 命令產生的。對多個檔處理時，需要確認它們可以應用相同的動作。

Scripts dependencies(Scripts 相依性)

The different packages are linked together through scripts dependencies. Each package is generated according to the following order :

1. unpack

2. build

3. install

However, you may require that another package be unpacked before building the current one for example. Adding this line to your script :

$SCRIPTS/unpack package1 

will force the toolchain to call the unpack script of the package1 package before executing the rest of the currently executed script.

不同的套件透過 scripts 相依性連結在一起。每個套件根據下列規則產生：

1. unpack
2. build
3. install

無論如何，舉例來說，你可以要求在建立目前套件之前先解壓縮另一個套件。加入底下一行到 script 中：

$SCRIPTS/unpack package1 

這將強迫工具集在執行目前 script 後續處理之前先呼叫 package1 裡的 unpack script。

Adding package to build process

In order for a new package to be included in the build process, you must add a line for it in scripts/gentree

為了將新套件包含在建立程序中，你必須為它增加一行到 scripts/gentree 裡。 (例如 $SCRIPTS/install webgui $1)

Example of url file

The following lines are the content of the url file from the linux package :

http://ftp.ch.kernel.org/pub/linux/kernel/v2.6/linux-2.6.12.3.tar.bz2 ftp://ftp.alsa-project.org/pub/kernel-patches/alsa-git-2005-06-22.patch.gz 

It determines URLs to be downloaded to get the package.

底下這幾行是 linux 套件裡 url 檔的內容：

http://ftp.ch.kernel.org/pub/linux/kernel/v2.6/linux-2.6.12.3.tar.bz2 ftp://ftp.alsa-project.org/pub/kernel-patches/alsa-git-2005-06-22.patch.gz 

它決定取得套件的下載點 URLs。

Example of unpack script

When this script is called the sources of the package are taken from the sources/ directory and unpacked in the build.arch/package/ directory.

All the optionnal patches present in the packages/package/patches/ directory also are applied.

The following lines are the content of the unpack file from the linux package :

#!/bin/sh . config/options 

This defines a shell script and includes the content of the config/options file.

Each package script has to start with these lines.

$SCRIPTS/install make $SCRIPTS/install sed $SCRIPTS/extract $1 "alsa-git*" $BUILD/$1* $SCRIPTS/unpack lzma 

This defines the package requirements. Before doing anything else, the GeeXboX toolchain will proceed with the instllation of the make and sed packages, extract the alsa-git archive into the linux build tree (where $1 always is the name of the current package) and then unpack the lzma package.

LINUX="`ls -d $BUILD/linux*`" sed "s/CONFIG_BLK_DEV_RAM_SIZE=.*/CONFIG_BLK_DEV_RAM_SIZE=$RAMDISK_SIZE/" $PACKAGES/linux/config/linux.$TARGET_ARCH.conf > $LINUX/.config cp $BUILD/lzma*/SRC/7zip/Compress/LZMA_C/LzmaDecode.[ch] $LINUX/lib/ sed -i "s%^int Lzma%static int Lzma%g" $LINUX/lib/LzmaDecode.[ch] 

Here we edit some configuration files.

yes "" | make config ARCH=$TARGET_ARCH -C $LINUX make prepare0 ARCH=$TARGET_ARCH -C $LINUX 

And then finally prepare the sources from being built.

當這個 script 被叫用時，套件的源碼取自 sources/ 目錄下，而且解壓到 build.arch/package/ 目錄中。

所有出現在 packages/package/patches/ 目錄裡的補丁檔也會被應用上去。

下列兩行是 linux 套件裡 unpack 檔的內容：

#!/bin/sh . config/options 

這步定義 shell script 並將 config/options 檔的內容含括進來(匯入其環境變數的設定)。

每一個套件 script 必須以上面這兩行開頭，以便保證其環境一致。

$SCRIPTS/install make $SCRIPTS/install sed $SCRIPTS/extract $1 "alsa-git*" $BUILD/$1* $SCRIPTS/unpack lzma 

這裡定義套件的要求。在做其他事之前，GeeXboX 工具集將先處理 make 與 sed 套件的安裝，並將 alsa-git案卷解壓縮進 linux build tree(此處的 $1 就是指目前套件名稱)，並解壓 lzma 套件。

LINUX="`ls -d $BUILD/linux*`" sed "s/CONFIG_BLK_DEV_RAM_SIZE=.*/CONFIG_BLK_DEV_RAM_SIZE=$RAMDISK_SIZE/" $PACKAGES/linux/config/linux.$TARGET_ARCH.conf > $LINUX/.config cp $BUILD/lzma*/SRC/7zip/Compress/LZMA_C/LzmaDecode.[ch] $LINUX/lib/ sed -i "s%^int Lzma%static int Lzma%g" $LINUX/lib/LzmaDecode.[ch] 

此處我們編輯某些組態檔(透過 sed)。

yes "" | make config ARCH=$TARGET_ARCH -C $LINUX make prepare0 ARCH=$TARGET_ARCH -C $LINUX 

然後在最後準備好源碼以便建立執行檔。

Example of build script

The following lines are the content of the build file from the linux package :

#!/bin/sh . config/options 

Inclusion of GeeXboX toolchain properties.

$SCRIPTS/build toolchain $SCRIPTS/build module-init-tools 

Ensure that the toolchain has been built, build it otherwise.

DEPMOD="`ls -d $ROOT/$BUILD/module-init-tool*/depmod`" LINUX="`ls -d $ROOT/$BUILD/linux*`" MODDIR="$LINUX/modules" export CROSS_COMPILE=$TARGET_PREFIX export ARCH=$TARGET_ARCH 

Export all build options.

rm -rf $MODDIR mkdir -p $MODDIR 

Remove previously built modules if they exist.

case $TARGET_ARCH in i386) make bzImage -C "$LINUX"  ;; ppc) unset LDFLAGS make vmlinux -C "$LINUX"  ;; esac make modules -C "$LINUX" make INSTALL_MOD_PATH=$MODDIR DEPMOD=$DEPMOD modules_install -C "$LINUX" 

Finally build the linux kernel and its drivers as modules.

rm -f $MODDIR/lib/modules/*/build rm -f $MODDIR/lib/modules/*/source 

Remove useless directories to prevent them to be installed in ISO at install time.

底下幾行是 linux 套件裡 build 的內容。

#!/bin/sh . config/options 

將 GeeXboX 工具集通用屬性含括進來。

$SCRIPTS/build toolchain $SCRIPTS/build module-init-tools 

確定工具集曾被建立，否則就先建立工具集。

DEPMOD="`ls -d $ROOT/$BUILD/module-init-tool*/depmod`" LINUX="`ls -d $ROOT/$BUILD/linux*`" MODDIR="$LINUX/modules" export CROSS_COMPILE=$TARGET_PREFIX export ARCH=$TARGET_ARCH 

匯出所有 build 選項(環境變數)。

rm -rf $MODDIR mkdir -p $MODDIR 

先移除前一次曾建立而且存在的模組。

case $TARGET_ARCH in i386) make bzImage -C "$LINUX"  ;; ppc) unset LDFLAGS make vmlinux -C "$LINUX"  ;; esac make modules -C "$LINUX" make INSTALL_MOD_PATH=$MODDIR DEPMOD=$DEPMOD modules_install -C "$LINUX" 

最後建立 linux 核心及驅動程式為模組。

rm -f $MODDIR/lib/modules/*/build rm -f $MODDIR/lib/modules/*/source 

移除無用的目錄以防止它們在安裝時被複製到 ISO 檔裡。

Example of install script

The following lines are the content of the install file from the linux package :

#!/bin/sh . config/options 

Inclusion of GeeXboX toolchain properties.

case "$2" in image) test "$3" != installator && INSTALL="$INSTALL/boot" mkdir -p $INSTALL case $TARGET_ARCH in i386) cp $BUILD/$1*/arch/$TARGET_ARCH/boot/bzImage $INSTALL/vmlinuz  ;; ppc) cp $BUILD/linux*/vmlinux $INSTALL/vmlinux $STRIP $INSTALL/vmlinux  ;; esac  ;; 

Check for the architecture and copy the kernel to the right place in ISO.

 modules) cp -r $BUILD/linux*/modules/* $INSTALL mkdir -p $INSTALL/etc cp $PACKAGES/linux/config/modules $INSTALL/etc cp $PACKAGES/linux/config/tvcard $INSTALL/etc  ;; esac 

Then copy all kernel drivers (modules) in ISO and put some of the runtime configuration files in /etc (of the ISO).

Note that $INSTALL always represents the installation path that will be compressed to generate the ISO.

下面幾行是 linux 套件裡 install 檔的內容：

#!/bin/sh . config/options 

將 GeeXboX 工具集通用屬性含括進來。

case "$2" in image) test "$3" != installator && INSTALL="$INSTALL/boot" mkdir -p $INSTALL case $TARGET_ARCH in i386) cp $BUILD/$1*/arch/$TARGET_ARCH/boot/bzImage $INSTALL/vmlinuz  ;; ppc) cp $BUILD/linux*/vmlinux $INSTALL/vmlinux $STRIP $INSTALL/vmlinux  ;; esac  ;; 

檢查 CPU 種類並複製核心到 ISO 正確位置。

 modules) cp -r $BUILD/linux*/modules/* $INSTALL mkdir -p $INSTALL/etc cp $PACKAGES/linux/config/modules $INSTALL/etc cp $PACKAGES/linux/config/tvcard $INSTALL/etc  ;; esac 

然後複製所有核心驅動程式(模組)到 ISO 檔，而且放置某些執行時期的組態檔到 ISO 檔裡的 /etc 目錄下。

注意 $INSTALL 總是顯示即將壓縮來產生 ISO 檔的安裝路徑