MokoMakefile/zh tw

From Openmoko

(Difference between revisions)
Jump to: navigation, search
(需求軟體)
Line 1: Line 1:
 
{{Languages|MokoMakefile}}
 
{{Languages|MokoMakefile}}
 +
 
MokoMakefile 是在設立Openmoko Build環境時儲存所有工作的Makefile。藉由自動化安裝新的Openmoko build環境的過程,它提供所有的開發人員相同的設定環境。
 
MokoMakefile 是在設立Openmoko Build環境時儲存所有工作的Makefile。藉由自動化安裝新的Openmoko build環境的過程,它提供所有的開發人員相同的設定環境。
  
Line 6: Line 7:
 
它會為BUILD 環境產物提供相同的重覆性,並且可以像BitBake script放入[[OpenEmbedded]] 般輕鬆維護,並且提供建立OpenEmbedded的標準化過程。
 
它會為BUILD 環境產物提供相同的重覆性,並且可以像BitBake script放入[[OpenEmbedded]] 般輕鬆維護,並且提供建立OpenEmbedded的標準化過程。
  
它不像是在 [[Building Openmoko 2007.1 from scratch|Building OpenMoko from scratch]]中所提到的手動設定過程。MokiMakefile並不會安裝任何程式到你的系統裡(即使是一般的使用者也可以使用)。
+
它不像是在[[Building Openmoko 2007.1 from scratch|Building Openmoko from scratch]]中所提到的手動設定過程。MokiMakefile並不會安裝任何程式到你的系統裡(即使是一般的使用者也可以使用)。
  
 
MokoMakefile is a wrapper around all that to make it easy to set up and maintain a development environment that fully complies with the setup instructions published by Openmoko.
 
MokoMakefile is a wrapper around all that to make it easy to set up and maintain a development environment that fully complies with the setup instructions published by Openmoko.
Line 26: Line 27:
  
 
=== 需求軟體 ===
 
=== 需求軟體 ===
OpenEmbedded 用來控制系統的版本是[http://monotone.ca monotone],它並不是由MokoMakefile下載及安裝的。如果你的套件並沒有提供套裝軟體,你可以從http://monotone.ca 下載並安裝 a static binary from http://monotone.ca
+
OpenEmbedded 用來控制系統的版本是[http://monotone.ca monotone],它並不是由MokoMakefile下載及安裝的。如果你的套件並沒有提供套裝軟體,你可以從http://monotone.ca 下載並安裝穩定的二進位檔。
 +
 
  
 
Some distribution specific hints on preparing your build host for building OpenEmbedded are on  http://www.openembedded.org/wiki/OEandYourDistro but they may be outdated, incomplete and do not cover everything which OpenMoko needs to build.
 
Some distribution specific hints on preparing your build host for building OpenEmbedded are on  http://www.openembedded.org/wiki/OEandYourDistro but they may be outdated, incomplete and do not cover everything which OpenMoko needs to build.
  
A good guide is [[Building OpenMoko from scratch#Build host prerequisites|the section on build host prerequisites]] in [[Building OpenMoko from scratch]]
+
[[Building OpenMoko from scratch#Build host prerequisites|the section on build host prerequisites]] in [[Building OpenMoko from scratch]]是很好的導引文章。
  
If you forgot anything which OE needs itself, OE will tell you shortly after you start building, but it does not check build dependencies of OpenMoko, so you either have to install them before starting or install them after the build failed. OpenEmbedded will continue where it stopped when you restart the build afterwards.
+
如果你忘記了OE本身所必須使用的東西,OE將會在你開始build時出現提示,但是它並不會查看Openmoko的BUILD獨立性,所以,你必須在開始前先安裝它,或者在build失敗之後安裝它們。OpenEmbedded 會在你上次中斷build的地方重新開始。
  
==== Package requirements by distribution ====
+
==== 依套件而衍生的套裝軟體需求 ====
 
Your distribution needs to provide these commands in order for OpenEmbedded to start building:
 
Your distribution needs to provide these commands in order for OpenEmbedded to start building:
 
  subversion texi2html texinfo help2man
 
  subversion texi2html texinfo help2man

Revision as of 08:53, 12 May 2008


MokoMakefile 是在設立Openmoko Build環境時儲存所有工作的Makefile。藉由自動化安裝新的Openmoko build環境的過程,它提供所有的開發人員相同的設定環境。

透過設定新的Openmoko build環境設定過程,它提供為所有現有的開發人員相同的設定,但一般較喜歡透過手動或個別的設定程序設定。

它會為BUILD 環境產物提供相同的重覆性,並且可以像BitBake script放入OpenEmbedded 般輕鬆維護,並且提供建立OpenEmbedded的標準化過程。

它不像是在Building Openmoko from scratch中所提到的手動設定過程。MokiMakefile並不會安裝任何程式到你的系統裡(即使是一般的使用者也可以使用)。

MokoMakefile is a wrapper around all that to make it easy to set up and maintain a development environment that fully complies with the setup instructions published by Openmoko.

MokoMakefile是由Rod Whitby 所開發--它並不是一個Openmoko正式的產品。 若它與official OpenMoko build instructions及MokoMakefile有差異之處,你應該考慮用正式的操作來修正它。 MokoMakefile 可以建立OM-2007.1 或OM-2007.2 影像檔。核心團隊選擇預設值,但是你可以選擇Makefile中的一些工具來使用。

MokoMakefile也可以建立QEMU-based Neo1973 模擬器,將它視為安裝及執行Openmoko映像檔的目標裝置。這些指令也可以在沒有下載整個Openmoko OpenEmbedded套件的狀況下下載及建立映像檔。你可以在Using QEMU with MokoMakefile中找到這個部份的說明。

Contents

建置Openmoko的需求

不論單獨或者是使用客製化的方法使用MokoMakefile來安裝Openmoko 環境,你必須符合某些需求,讓Openmoko build 可以成功運做:

  • RAM:build host 必須擁有至少512MB的RAM,及與它相同大小的swap空間。有一些套件像是busybox由OpenEmbedded建立,它是藉由先編譯所有的來源檔案,使它成為二進位檔,它會讓 gcc 增加為超過 300MB 的大小,因此,會導致沒有記憶體可以用做swap之用,造成無法預期編譯時間的狀況。

對於busybox,這個可以關閉它,但關閉它並不會表示它能被gcc最佳化。

  • 磁碟空間:你必須擁有12 GB的可用硬碟空間,供給Openmoko build使用(你可以參考下面的文節暸解怎麼減少所需磁碟空間用量)。
  • 時間:initial build 會花費至少5小時的時間 (在沒有最佳化的多處理器的 2GHz core2duo 硬體環境下)且,在更慢速度的環境下,它可能會花費更長的時間。

需求軟體

OpenEmbedded 用來控制系統的版本是monotone,它並不是由MokoMakefile下載及安裝的。如果你的套件並沒有提供套裝軟體,你可以從http://monotone.ca 下載並安裝穩定的二進位檔。


Some distribution specific hints on preparing your build host for building OpenEmbedded are on http://www.openembedded.org/wiki/OEandYourDistro but they may be outdated, incomplete and do not cover everything which OpenMoko needs to build.

the section on build host prerequisites in Building OpenMoko from scratch是很好的導引文章。

如果你忘記了OE本身所必須使用的東西,OE將會在你開始build時出現提示,但是它並不會查看Openmoko的BUILD獨立性,所以,你必須在開始前先安裝它,或者在build失敗之後安裝它們。OpenEmbedded 會在你上次中斷build的地方重新開始。

依套件而衍生的套裝軟體需求

Your distribution needs to provide these commands in order for OpenEmbedded to start building:

subversion texi2html texinfo help2man

OpenMoko needs the development packages (with header files, development libraries and tools) in order to finish building:

ncurses zlib (or libz) OpenSSL GTK++

Because there are bugs in the interaction of QEMU and GCC-4, you'll need a copy of gcc-3.x installed as well.

Debian / Ubuntu
 apt-get install subversion monotone build-essential help2man diffstat texi2html texinfo cvs gawk cogito
 apt-get install libncurses5-dev zlib1g-dev libssl-dev libgtk2.0-dev 
 # To prevent errors in host validation
 apt-get install ca-certificates
 # For OpenMoko 2007.2 using BitBake-1.8.8:
 apt-get install python-pysqlite2 sqlite3 sqlite3-doc python-pysqlite2-dbg
 # For building faster
 apt-get install quilt python-psyco ccache
 # For qemu, install a second compiler for bug avoidance; MokoMakefile knows to look for it.
 apt-get install gcc-3.4 g++-3.4 libsdl1.2-dev lynx netpbm dosfstools
SuSE

For building Openmoko on 10.3, you need

gcc-c++ ncurses-devel zlib-devel libopenssl-devel gtk2-devel subversion diffstat texinfo help2man and monotone

For MokoMakefile to not fail on compiling qemu-user, you need to use gcc33:

wget download.opensuse.org/repositories/devel:/tools:/gcc/openSUSE_Factory/i586/{cpp,gcc}33-3.3.3-41.8.i586.rpm
rpm -Uhv {cpp,gcc}33-3.3.3-41.8.i586.rpm

See also the Talk page on Building on SuSE Linux 10.3-AMD64

10.1 and 10.2: same packages as 10.3, but install openssl-devel instead of libopenssl-devel. Use monotone for 10.2 or 10.1

For all distributions

As the QEMU-based neo1973 emulator is also built as part of the build process started by MokoMakefile, so you need gcc-3.3 and other packages for building QEMU installed. See the build requirements section in Using QEMU with MokoMakefile for information on the required software.

If you are having problems compiling QEMU and do not need it, you can disable building of QEMU by adding following line to build/conf/local.conf file:

ENABLE_BINARY_LOCALE_GENERATION = "0"

Building OpenMoko with MokoMakefile

1 - Create your $OMDIR directory (note that you can change ~/moko to any directory you like. If you have your ~moko dir mounted from a different file system, be sure to edit /etc/mtab to add the 'exec' permission to the file system, else bitbake will fail with error messages stating that /usr/bin/env is an invalid interpreter):

  mkdir ~/moko ; cd ~/moko

2 - Grab MokoMakefile:

  wget http://www.rwhitby.net/files/openmoko/Makefile

If that doesn't work, try

  wget http://svn.projects.openmoko.org/svnroot/mokomakefile/trunk/Makefile
  note: If you want to compile for the old version 2007.1 instead of the new
        version edit the top of the Makefile. Edit the lines at the top to 
        look like this:
            OPENMOKO_GENERATION = 2007.1
            #OPENMOKO_GENERATION = 2007.2
NOTE: For building 2007.2, MokoMakefile uses BitBake 1.8.8 which requires python-sqlite2 and sqlite-3.3 or later. Users of SUSE Linux 10.1 can update to the version of openSUSE 10.2


3 - Set up the environment:

  make setup

4 - Start building. Before starting a lengthy make process, check the Tips section below for how to make Make multicore aware. You may want to modify the build/conf/local.conf file for your target (emulation/chroot) environment:

  make openmoko-devel-image

Hint: The images build with this command can be found under {$OMDIR}/build/tmp/deploy/images/neo1973

This will set up the recommended directory structure as described in Building OpenMoko from scratch, will download all the required software (from the right places with the right versions), and will immediately start building an image.

Once you have done this, you can choose to continue using the MokoMakefile to initiate your subsequent builds, or you can go into the build directory and run bitbake commands manually. The choice is yours.

Updating the environment

For easy maintenance of your build environment the following commands are available.

1 - To update the MokoMakefile to the latest version:

  make update-makefile 

2 - To make sure that any recent changes to the build directory structure have been applied:

  make setup 

3 - To update the OpenMoko repository checkout and the MokoMakefile patches to the latest version:

  make update

A quick way to rebuild a new image with the latest updates:

  make update-makefile && make setup update openmoko-devel-image

Build issues

First, make sure that the problem is reproducible after running

make update-makefile && make setup && make update

then run

make clean-package-<foo>

(where you replace <foo> with the name of the package which is failing)

and finally

make openmoko-devel-image

With luck - you should now have images in your $omdir/build/tmp/deploy/glibc/images/neo1973/ directory. You can then |flash these.


If not, and you can get the error to occur three times in a row after running that sequence of commands (including the update and setup steps) three times, then feel free to report it to rwhitby in #openmoko on IRC.

Known MokoMakefile errors

If you experience the following after changing from OM-2007.1 to OM-2007.2:

Patch bitbake-1.6.6-om3.patch does not apply (enforce with -f)

then type "make clobber-patches" to fix it. There was a period of 24 hours when there was a bug in the MokoMakefile which causes this problem. Once the patches have been clobbered, they will re-download and the problem will not reoccur.

If you see:

ERROR: No providers of build target u-boot-openmoko (for [])

then look back in the log to see if you encountered an earlier error while building the openmoko-devel-image target. The above error is a side-effect of MokoMakefile's logic to handle the re-naming of "uboot-openmoko" to "u-boot-openmoko".

Fixes for distribution/environment-specific or isolated issues

Work-arounds for temporary or isolated problems can be found and should be added to the Discussion page which is associated with this page. As they are fixed, they will be removed from that page.

Tips

  • You can reduce the amount of consumed disk space significantly by adding
  INHERIT += "rm_work"

in your local.conf (e.g. ~/moko/build/conf/local.conf). This will remove the contents of each build/tmp/work/*/<package> directory after the corresponding package builds correctly. As of 10/16/07, this appears to be present in local.conf by default.

  • If you an encounter an error with monotone similar to the following:
  mtn: misuse: database /home/username/moko/OE.mtn is laid out according to an old schema

Then you need to upgrade OE.mtn Use the following command while in ~/moko:

  # mtn --db OE.mtn db migrate
  • If a certain package does not build due to corrupted download or some such try to remove the sources and rebuild it.
rm sources/<package>*
cd build
. ../setup-env
bitbake -crebuild <package>

after that your build might just work again.

  • For people with multiple CPU's (or dual-core ones) this small patch might be useful to build things faster.

Edit the local.conf and add the following lines:

PARALLEL_MAKE = "-j 4"
BB_NUMBER_THREADS = "4"

Change the PARALLEL_MAKE and BB_NUMBER_THREADS values to something that suits better if it chokes your machine.

  • If you encounter an error related with the qemu-native package and not compiling for the qemu, you can edit the build/conf/local.conf file and add ENABLE_BINARY_LOCALE_GENERATION = "0" line to avoid the error.
  • To prevent building tons of locales, add a line like this to local.conf:
GLIBC_GENERATE_LOCALES = "en_US.UTF-8 nl_NL.UTF-8"
  • To not build any binary locales at all, add this to local.conf:
ENABLE_BINARY_LOCALE_GENERATION = "0"
  • If you want to rebuild the package indexes (for instance, after compiling a new version of a package) without building openmoko-devel-image, run make build-package-package-index.

User:Wurp will update this to be a little more comprehensible, but maybe it can help someone as-is in the meantime:

  • If MokoMakefile always fails on some fetch in zlib, just find the binary somewhere, add it to the downloads or sources directory manually (create the .md5 matching file if necessary), and retry.

Useful commands

Here is the list (not complete) of useful MokoMakefile commands (actually make targets) and a short description of each one. These should be run inside $OMDIR directory.

make openmoko-devel-image 
build the full development image
make openmoko-devel-tools 
build statically-linked dfu-util and openocd binaries
make openmoko-toolchain 
builds toolchain
make qemu 
builds qemu, downloads flash images from official repository, flashes qemu emulated Neo1973 and runs emulator (see also OpenMoko under QEMU).
make qemu-local 
same as make qemu, but uses locally built images instead of official ones.
make run-qemu 
runs qemu with usb keyboard (note: qemu must first be built!). This target starts the emulator with some predefined set of options. If you need to start it with other options (enable telnet, etc), see QEMU_command_line.
make build-package-<package name> 
buids <package name> package
make update-makefile 
updates MokoMakefile
make clean-package-<foo>
cleans the "<foo>" package
make setup 
to make sure that any recent changes to the build directory structure have been applied
make update 
to update the OpenMoko repository checkout and the MokoMakefile patches to the latest version

Developing with MokoMakefile

NOTE: If using MokoMakefile with OM2007.2 then references to $OMDIR/openmoko should be replaced with $OMDIR/openembedded. Also references to tmp/work/armv4t-linux should be replaced with tmp/work/fic-gta01-angstrom-linux-gnueabi


For the following explanations $OMDIR is the directory where there Makefile puts all the stuff.

To make in-tree changes and have them built and used by qemu:

 cd $OMDIR/openmoko
 quilt new descriptive-patch-name.patch
 quilt add trunk/src/name-of-file-to-change # do this for every file you are about to modify
 ...make the changes...
 quilt refresh # this creates a file in $OMDIR/patches/openmoko-HEAD/ and updates the quilt series file there

Note: Do NOT use absolute paths as this confuses quilt and will get you a diff of the file against /dev/null!

To build the changes and have them used by qemu:

 make build-qemu
 make flash-qemu-local
 make run-qemu

If you want to modify applications instead of the openmoko toolchain, this is what you have to do (example: openmoko-messages):

 cd $OMDIR/build
 . ../setup-env
 bitbake -c unpack openmoko-messages
 cd tmp/work/armv4t-linux/openmoko-messages-0.0.1+svnnow-r2_2276/openmoko-messages/
 ...make the changes...
 cd -
 bitbake openmoko-messages

Then continue with MokoMakefile usage.

If you want to add an application to your openmoko distribution, do this: All file edits should be done using quilt as described above. That way a patch can easily be submitted to the openmoko project. First, create a directory that will correspond to your package and edit a .bb file in there:

 cd $OMDIR/openmoko/
 quilt new mycoolpackage.patch
 mkdir trunk/oe/packages/mycoolpackage
 quilt add trunk/oe/packages/mycoolpackage/mycoolpackage_1.bb
 quilt edit trunk/oe/packages/mycoolpackage/mycoolpackage_1.bb

The file should have the following content:

 DESCRIPTION = "This is a cool package"
 SECTION = "username/mycoolpackage"
 PV = "1"
 
 inherit autotools
 
 SRC_URI = "http://www.example.com/download/mycoolpackage-1.tar.gz"

Explanation:

  • DESCRIPTION - Just a short text explaining the package
  • SECTION - I have no clue, but I'll use username/mycoolpackage for now
  • PV - Package Version
  • inherit autotools - The package can be compiled by './configure && make && make install' so we tell MokoMakefile to do it this way.
  • SRC_URI = ... - This is the download location of the package source. It's imperative that the tar.gz contains a directory called packagename-packageversion (in this case: mycoolpackage-1) so that MokoMakefile can find it automatically or the build will fail.

This is not all. We also need to tell MokoMakfile that it needs to build and include the package in the image. To do this, do

 $OMDIR/openmoko# quilt edit trunk/oe/packages/tasks/task-openmoko.bb

Here, increase the value PR by one and add mycoolpackage \ (with the backslash!) just before the line reading # update-alternatives \.

Now run

 quilt refresh
 cd ..
 make update openmoko-devel-image

And if everything's alright you should now have an OpenMoko image to flash to your phone or run in qemu as described above.

Hello World application

There is a Hello World! tutorial available too.

Testimonials

MokoMakefile is recommended by 4 out of 4 new developers on #openmoko, with testimonials such as "For some reason last night I couldn't get my manual install of everything to work (bb complained about my bbpath I think) ... but with your makefile, it works great!", "MokoMakefile rocks!", "Wow this build system is nice - it just seems more polished than my gumstix toolchain buildroot system", and "make openmoko-devel-image :) - no magic there".

Project page: http://mokomakefile.projects.openmoko.org/

Personal tools

MokoMakefile 是在設立Openmoko Build環境時儲存所有工作的Makefile。藉由自動化安裝新的Openmoko build環境的過程,它提供所有的開發人員相同的設定環境。

透過設定新的Openmoko build環境設定過程,它提供為所有現有的開發人員相同的設定,但一般較喜歡透過手動或個別的設定程序設定。

它會為BUILD 環境產物提供相同的重覆性,並且可以像BitBake script放入OpenEmbedded 般輕鬆維護,並且提供建立OpenEmbedded的標準化過程。

它不像是在 Building OpenMoko from scratch中所提到的手動設定過程。MokiMakefile並不會安裝任何程式到你的系統裡(即使是一般的使用者也可以使用)。

MokoMakefile is a wrapper around all that to make it easy to set up and maintain a development environment that fully complies with the setup instructions published by Openmoko.

MokoMakefile是由Rod Whitby 所開發--它並不是一個Openmoko正式的產品。 若它與official OpenMoko build instructions及MokoMakefile有差異之處,你應該考慮用正式的操作來修正它。 MokoMakefile 可以建立OM-2007.1 或OM-2007.2 影像檔。核心團隊選擇預設值,但是你可以選擇Makefile中的一些工具來使用。

MokoMakefile也可以建立QEMU-based Neo1973 模擬器,將它視為安裝及執行Openmoko映像檔的目標裝置。這些指令也可以在沒有下載整個Openmoko OpenEmbedded套件的狀況下下載及建立映像檔。你可以在Using QEMU with MokoMakefile中找到這個部份的說明。

建置Openmoko的需求

不論單獨或者是使用客製化的方法使用MokoMakefile來安裝Openmoko 環境,你必須符合某些需求,讓Openmoko build 可以成功運做:

  • RAM:build host 必須擁有至少512MB的RAM,及與它相同大小的swap空間。有一些套件像是busybox由OpenEmbedded建立,它是藉由先編譯所有的來源檔案,使它成為二進位檔,它會讓 gcc 增加為超過 300MB 的大小,因此,會導致沒有記憶體可以用做swap之用,造成無法預期編譯時間的狀況。

對於busybox,這個可以關閉它,但關閉它並不會表示它能被gcc最佳化。

  • 磁碟空間:你必須擁有12 GB的可用硬碟空間,供給Openmoko build使用(你可以參考下面的文節暸解怎麼減少所需磁碟空間用量)。
  • 時間:initial build 會花費至少5小時的時間 (在沒有最佳化的多處理器的 2GHz core2duo 硬體環境下)且,在更慢速度的環境下,它可能會花費更長的時間。

需求軟體

OpenEmbedded 用來控制系統的版本是monotone,它並不是由MokoMakefile下載及安裝的。如果你的套件並沒有提供套裝軟體,你可以從http://monotone.ca 下載並安裝 a static binary from http://monotone.ca

Some distribution specific hints on preparing your build host for building OpenEmbedded are on http://www.openembedded.org/wiki/OEandYourDistro but they may be outdated, incomplete and do not cover everything which OpenMoko needs to build.

A good guide is the section on build host prerequisites in Building OpenMoko from scratch

If you forgot anything which OE needs itself, OE will tell you shortly after you start building, but it does not check build dependencies of OpenMoko, so you either have to install them before starting or install them after the build failed. OpenEmbedded will continue where it stopped when you restart the build afterwards.

Package requirements by distribution

Your distribution needs to provide these commands in order for OpenEmbedded to start building:

subversion texi2html texinfo help2man

OpenMoko needs the development packages (with header files, development libraries and tools) in order to finish building:

ncurses zlib (or libz) OpenSSL GTK++

Because there are bugs in the interaction of QEMU and GCC-4, you'll need a copy of gcc-3.x installed as well.

Debian / Ubuntu
 apt-get install subversion monotone build-essential help2man diffstat texi2html texinfo cvs gawk cogito
 apt-get install libncurses5-dev zlib1g-dev libssl-dev libgtk2.0-dev 
 # To prevent errors in host validation
 apt-get install ca-certificates
 # For OpenMoko 2007.2 using BitBake-1.8.8:
 apt-get install python-pysqlite2 sqlite3 sqlite3-doc python-pysqlite2-dbg
 # For building faster
 apt-get install quilt python-psyco ccache
 # For qemu, install a second compiler for bug avoidance; MokoMakefile knows to look for it.
 apt-get install gcc-3.4 g++-3.4 libsdl1.2-dev lynx netpbm dosfstools
SuSE

For building Openmoko on 10.3, you need

gcc-c++ ncurses-devel zlib-devel libopenssl-devel gtk2-devel subversion diffstat texinfo help2man and monotone

For MokoMakefile to not fail on compiling qemu-user, you need to use gcc33:

wget download.opensuse.org/repositories/devel:/tools:/gcc/openSUSE_Factory/i586/{cpp,gcc}33-3.3.3-41.8.i586.rpm
rpm -Uhv {cpp,gcc}33-3.3.3-41.8.i586.rpm

See also the Talk page on Building on SuSE Linux 10.3-AMD64

10.1 and 10.2: same packages as 10.3, but install openssl-devel instead of libopenssl-devel. Use monotone for 10.2 or 10.1

For all distributions

As the QEMU-based neo1973 emulator is also built as part of the build process started by MokoMakefile, so you need gcc-3.3 and other packages for building QEMU installed. See the build requirements section in Using QEMU with MokoMakefile for information on the required software.

If you are having problems compiling QEMU and do not need it, you can disable building of QEMU by adding following line to build/conf/local.conf file:

ENABLE_BINARY_LOCALE_GENERATION = "0"

Building OpenMoko with MokoMakefile

1 - Create your $OMDIR directory (note that you can change ~/moko to any directory you like. If you have your ~moko dir mounted from a different file system, be sure to edit /etc/mtab to add the 'exec' permission to the file system, else bitbake will fail with error messages stating that /usr/bin/env is an invalid interpreter):

  mkdir ~/moko ; cd ~/moko

2 - Grab MokoMakefile:

  wget http://www.rwhitby.net/files/openmoko/Makefile

If that doesn't work, try

  wget http://svn.projects.openmoko.org/svnroot/mokomakefile/trunk/Makefile
  note: If you want to compile for the old version 2007.1 instead of the new
        version edit the top of the Makefile. Edit the lines at the top to 
        look like this:
            OPENMOKO_GENERATION = 2007.1
            #OPENMOKO_GENERATION = 2007.2
NOTE: For building 2007.2, MokoMakefile uses BitBake 1.8.8 which requires python-sqlite2 and sqlite-3.3 or later. Users of SUSE Linux 10.1 can update to the version of openSUSE 10.2


3 - Set up the environment:

  make setup

4 - Start building. Before starting a lengthy make process, check the Tips section below for how to make Make multicore aware. You may want to modify the build/conf/local.conf file for your target (emulation/chroot) environment:

  make openmoko-devel-image

Hint: The images build with this command can be found under {$OMDIR}/build/tmp/deploy/images/neo1973

This will set up the recommended directory structure as described in Building OpenMoko from scratch, will download all the required software (from the right places with the right versions), and will immediately start building an image.

Once you have done this, you can choose to continue using the MokoMakefile to initiate your subsequent builds, or you can go into the build directory and run bitbake commands manually. The choice is yours.

Updating the environment

For easy maintenance of your build environment the following commands are available.

1 - To update the MokoMakefile to the latest version:

  make update-makefile 

2 - To make sure that any recent changes to the build directory structure have been applied:

  make setup 

3 - To update the OpenMoko repository checkout and the MokoMakefile patches to the latest version:

  make update

A quick way to rebuild a new image with the latest updates:

  make update-makefile && make setup update openmoko-devel-image

Build issues

First, make sure that the problem is reproducible after running

make update-makefile && make setup && make update

then run

make clean-package-<foo>

(where you replace <foo> with the name of the package which is failing)

and finally

make openmoko-devel-image

With luck - you should now have images in your $omdir/build/tmp/deploy/glibc/images/neo1973/ directory. You can then |flash these.


If not, and you can get the error to occur three times in a row after running that sequence of commands (including the update and setup steps) three times, then feel free to report it to rwhitby in #openmoko on IRC.

Known MokoMakefile errors

If you experience the following after changing from OM-2007.1 to OM-2007.2:

Patch bitbake-1.6.6-om3.patch does not apply (enforce with -f)

then type "make clobber-patches" to fix it. There was a period of 24 hours when there was a bug in the MokoMakefile which causes this problem. Once the patches have been clobbered, they will re-download and the problem will not reoccur.

If you see:

ERROR: No providers of build target u-boot-openmoko (for [])

then look back in the log to see if you encountered an earlier error while building the openmoko-devel-image target. The above error is a side-effect of MokoMakefile's logic to handle the re-naming of "uboot-openmoko" to "u-boot-openmoko".

Fixes for distribution/environment-specific or isolated issues

Work-arounds for temporary or isolated problems can be found and should be added to the Discussion page which is associated with this page. As they are fixed, they will be removed from that page.

Tips

  • You can reduce the amount of consumed disk space significantly by adding
  INHERIT += "rm_work"

in your local.conf (e.g. ~/moko/build/conf/local.conf). This will remove the contents of each build/tmp/work/*/<package> directory after the corresponding package builds correctly. As of 10/16/07, this appears to be present in local.conf by default.

  • If you an encounter an error with monotone similar to the following:
  mtn: misuse: database /home/username/moko/OE.mtn is laid out according to an old schema

Then you need to upgrade OE.mtn Use the following command while in ~/moko:

  # mtn --db OE.mtn db migrate
  • If a certain package does not build due to corrupted download or some such try to remove the sources and rebuild it.
rm sources/<package>*
cd build
. ../setup-env
bitbake -crebuild <package>

after that your build might just work again.

  • For people with multiple CPU's (or dual-core ones) this small patch might be useful to build things faster.

Edit the local.conf and add the following lines:

PARALLEL_MAKE = "-j 4"
BB_NUMBER_THREADS = "4"

Change the PARALLEL_MAKE and BB_NUMBER_THREADS values to something that suits better if it chokes your machine.

  • If you encounter an error related with the qemu-native package and not compiling for the qemu, you can edit the build/conf/local.conf file and add ENABLE_BINARY_LOCALE_GENERATION = "0" line to avoid the error.
  • To prevent building tons of locales, add a line like this to local.conf:
GLIBC_GENERATE_LOCALES = "en_US.UTF-8 nl_NL.UTF-8"
  • To not build any binary locales at all, add this to local.conf:
ENABLE_BINARY_LOCALE_GENERATION = "0"
  • If you want to rebuild the package indexes (for instance, after compiling a new version of a package) without building openmoko-devel-image, run make build-package-package-index.

User:Wurp will update this to be a little more comprehensible, but maybe it can help someone as-is in the meantime:

  • If MokoMakefile always fails on some fetch in zlib, just find the binary somewhere, add it to the downloads or sources directory manually (create the .md5 matching file if necessary), and retry.

Useful commands

Here is the list (not complete) of useful MokoMakefile commands (actually make targets) and a short description of each one. These should be run inside $OMDIR directory.

make openmoko-devel-image 
build the full development image
make openmoko-devel-tools 
build statically-linked dfu-util and openocd binaries
make openmoko-toolchain 
builds toolchain
make qemu 
builds qemu, downloads flash images from official repository, flashes qemu emulated Neo1973 and runs emulator (see also OpenMoko under QEMU).
make qemu-local 
same as make qemu, but uses locally built images instead of official ones.
make run-qemu 
runs qemu with usb keyboard (note: qemu must first be built!). This target starts the emulator with some predefined set of options. If you need to start it with other options (enable telnet, etc), see QEMU_command_line.
make build-package-<package name> 
buids <package name> package
make update-makefile 
updates MokoMakefile
make clean-package-<foo>
cleans the "<foo>" package
make setup 
to make sure that any recent changes to the build directory structure have been applied
make update 
to update the OpenMoko repository checkout and the MokoMakefile patches to the latest version

Developing with MokoMakefile

NOTE: If using MokoMakefile with OM2007.2 then references to $OMDIR/openmoko should be replaced with $OMDIR/openembedded. Also references to tmp/work/armv4t-linux should be replaced with tmp/work/fic-gta01-angstrom-linux-gnueabi


For the following explanations $OMDIR is the directory where there Makefile puts all the stuff.

To make in-tree changes and have them built and used by qemu:

 cd $OMDIR/openmoko
 quilt new descriptive-patch-name.patch
 quilt add trunk/src/name-of-file-to-change # do this for every file you are about to modify
 ...make the changes...
 quilt refresh # this creates a file in $OMDIR/patches/openmoko-HEAD/ and updates the quilt series file there

Note: Do NOT use absolute paths as this confuses quilt and will get you a diff of the file against /dev/null!

To build the changes and have them used by qemu:

 make build-qemu
 make flash-qemu-local
 make run-qemu

If you want to modify applications instead of the openmoko toolchain, this is what you have to do (example: openmoko-messages):

 cd $OMDIR/build
 . ../setup-env
 bitbake -c unpack openmoko-messages
 cd tmp/work/armv4t-linux/openmoko-messages-0.0.1+svnnow-r2_2276/openmoko-messages/
 ...make the changes...
 cd -
 bitbake openmoko-messages

Then continue with MokoMakefile usage.

If you want to add an application to your openmoko distribution, do this: All file edits should be done using quilt as described above. That way a patch can easily be submitted to the openmoko project. First, create a directory that will correspond to your package and edit a .bb file in there:

 cd $OMDIR/openmoko/
 quilt new mycoolpackage.patch
 mkdir trunk/oe/packages/mycoolpackage
 quilt add trunk/oe/packages/mycoolpackage/mycoolpackage_1.bb
 quilt edit trunk/oe/packages/mycoolpackage/mycoolpackage_1.bb

The file should have the following content:

 DESCRIPTION = "This is a cool package"
 SECTION = "username/mycoolpackage"
 PV = "1"
 
 inherit autotools
 
 SRC_URI = "http://www.example.com/download/mycoolpackage-1.tar.gz"

Explanation:

  • DESCRIPTION - Just a short text explaining the package
  • SECTION - I have no clue, but I'll use username/mycoolpackage for now
  • PV - Package Version
  • inherit autotools - The package can be compiled by './configure && make && make install' so we tell MokoMakefile to do it this way.
  • SRC_URI = ... - This is the download location of the package source. It's imperative that the tar.gz contains a directory called packagename-packageversion (in this case: mycoolpackage-1) so that MokoMakefile can find it automatically or the build will fail.

This is not all. We also need to tell MokoMakfile that it needs to build and include the package in the image. To do this, do

 $OMDIR/openmoko# quilt edit trunk/oe/packages/tasks/task-openmoko.bb

Here, increase the value PR by one and add mycoolpackage \ (with the backslash!) just before the line reading # update-alternatives \.

Now run

 quilt refresh
 cd ..
 make update openmoko-devel-image

And if everything's alright you should now have an OpenMoko image to flash to your phone or run in qemu as described above.

Hello World application

There is a Hello World! tutorial available too.

Testimonials

MokoMakefile is recommended by 4 out of 4 new developers on #openmoko, with testimonials such as "For some reason last night I couldn't get my manual install of everything to work (bb complained about my bbpath I think) ... but with your makefile, it works great!", "MokoMakefile rocks!", "Wow this build system is nice - it just seems more polished than my gumstix toolchain buildroot system", and "make openmoko-devel-image :) - no magic there".

Project page: http://mokomakefile.projects.openmoko.org/