Openembedded.org - User contributions [en]

Category talk:FAQ

2010-05-28T15:07:24Z

Jhelwig: Undo revision 2317 by 212.235.107.114 (Talk)

= Old Wiki Faq =

The old wiki installation seems to have eaten the FAQ page. Let's try to restore some of the information from [http://web.archive.org/web/20070222090436/www.openembedded.org/node/28/edit web.archive.org], this will need to be compared with [http://74.125.39.104/search?q=cache%3Aoe.linuxtogo.org%2Fnode%2F28%2Fdiff%2F1140&ie=utf-8&oe=utf-8&aq=t&rls=com.ubuntu:en-US:unofficial&client=firefox-a the last known-good version] from google (mark all text on that page to make it visible). Content still to be moved follows

--[[User:Laibsch|Laibsch]] 23:08, 4 June 2008 (UTC)

= Development =

== 1. what does OpenEmbedded keyword X do? ==
Check out the documentation in the following file: http://www.openembedded.org/repo/org.openembedded.dev/conf/documentation.conf

== 2. How can I make bitbake to use a specific version of <tool>? ==
See [http://www.openembedded.org/search/node/PREFERRED_VERSION PREFERRED_VERSION]

== 3. How can I make bitbake use proxychains when doing cvs operations? ==
See [http://www.openembedded.org/search/node/FETCH_COMMAND FETCH_COMMAND] and [http://www.openembedded.org/search/node/UPDATE_COMMAND UPDATE_COMMAND]

== 4. What is the easiest way to convert Debian ARM packages to ipkg's (if size doesn't matter)? ==
mv foo.deb foo.ipk

== 5. How do I add a package to OE? ==
Most of the time adding a package to OE will not be as easy as 1-2-3. Many software developers do not cross-compile their packages and are generally unaware of [[Users Manual/Rules Of Thumb|good design decisions]] that facilitate or break cross-compilation.

== 6. How can I do a recursive make? ==

Implement a structure along the following lines.

do_compile {
for i in dir; oe_runmake ...; done
}

== 7. How do I set a variable according to the kernel version of the package being built? ==

Use base_conditional in the following manner:

CFLAGS_append = '${@base_conditional("KERNEL_MAJOR_VERSION", "2.6", " -D__Linux26__ ", " -D__Linux24__ ",d)}'

In the example above ''-D__Linux26__'' will be added to the existing CFLAGS if the kernel is 2.6 and ''-D__Linux24__'' if the kernel is 2.4

== 8. What is ARM EABI and how do I use it? ==
ARM EABI is the informal name for the ABI for the ARM Architecture standard developed by ARM Ltd and others. This standard explains how tools should generate object and excecutable files.
* http://www.codesourcery.com/gnu_toolchains/arm/faq.html#q_gnu_linux_long_long
* http://www.arm.com/products/DevTools/ABI.html
* http://wiki.debian.org/ArmEabiPort

To instruct OE to build EABI parts, you typically need the following in your distro conf file:
TARGET_OS=-gnueabi
See the Angstrom distro for an example: http://www.openembedded.org/repo/org.openembedded.dev/conf/distro/angstrom.conf
http://www.openembedded.org/repo/org.openembedded.dev/conf/distro/angstrom-2006.9.conf

You also need to make sure your kernel has the needed support. From the codesourcery faq, you need the following:
* CONFIG_EABI must be enabled
* Kernel must include support for NPTL
* kernel versions earlier than 2.6.17 should be avoided

== 9. What is NPTL and how do I use it in OE? ==
NPTL is the Native POSIX Thread Library which is a software feature that enables the Linux kernel to run programs written to use POSIX Threads very efficiently. It is meant to replace an older implementation named Linuxthreads.
* [http://en.wikipedia.org/wiki/LinuxThreads]
* [http://en.wikipedia.org/wiki/Native_POSIX_Thread_Library]
* to check what threading library you have, run the following command: getconf GNU_LIBPTHREAD_VERSION. You can also type:
/lib/libc.so.6 to get information on what threading lib is used.

There are two options for threading (from pb email):
* With linuxthreads, you need glibc-initial, then gcc-cross-initial,
then glibc, then gcc-cross.
* With nptl, you need glibc-initial, then gcc-cross-initial, then
glibc-intermediate, then gcc-cross, then glibc.

To use linuxthreads, you need something like the following:
PREFERRED_PROVIDER_virtual/${TARGET_PREFIX}libc-for-gcc = glibc

For NPTL, this becomes:
PREFERRED_PROVIDER_virtual/${TARGET_PREFIX}libc-for-gcc = glibc-intermediate

== 10. How do I apply for read-write status to the OpenEmbedded monotone repo? ==

Hang around IRC in #oe, use the dev mailing list or some other way to get in [http://www.openembedded.org/contact contact] with the OE devs. Explain to them why you think you should be given rw access. If your request is granted, [http://www.openembedded.org/wiki/MonotonePhraseBook create your key and send it to the maintainers].

== 11. How do I add additional packages to a bootstrap-image generated image? ==

You can add packages to your build by setting the MACHINE_EXTRA_RDEPENDS or DISTRO_EXTRA_RDEPENDS in a conf file. Note, you must rebuild task-base after changing these variables (bitbake task-base -crebuild) as bitbake has no way of knowing task-base has changed. See [http://bec-systems.com/web/content/view/59/9/] for a more detailed explanation.

== 12. What order are conf files parsed for variable assignment? ==
See oe/conf/bitbake.conf. There should be a section that looks something like:

<pre>
include conf/site.conf
include conf/auto.conf
include conf/local.conf
include conf/build/${BUILD_SYS}.conf
include conf/target/${TARGET_SYS}.conf
include conf/machine/${MACHINE}.conf
include conf/distro/${DISTRO}.conf
include conf/documentation.conf
require conf/sanity.conf
</pre>

A straight "=" assignment in a machine or distro conf file will overwrite a local.conf setting. Therefore, machine and distro conf files should use the "+=" assignment if it is useful for local.conf to be able to append to a variable.

= Build Errors =
== 1. chown error during do_install process ==
As the OE build process runs a normal using, any install process that changes file ownership or groups must be run using fakeroot. This typically involves the following change in the recipe bb file:
<pre><nowiki>
fakeroot do_install () {
oe_runmake "DSTROOT=${D}" install
}
</nowiki></pre>

== 2. Error: autoreconf2.50: unrecognized option --exclude=libtoolize ==
For some reason the base system's autoreconf is being used instead of the OE version (from autoconf-native)

For me personally this was a problem with my BBPATH having the paths to two branches in it org.openembedded.oz354x and org.openembedded.dev. Removing the one i wasn't trying to build, remove the tmp dir and start bitbake over fixed it.

== 3. Error: Building libtool-native dies with "configure: error: source directory already configured; run "make distclean" there first" ==
Your build dir path has one or more symlinks in it. Don't do that!

== 4. Error: run.do_patchcleancmd.4326: line 442: syntax error near unexpected token `'INHIBIT_PACKAGE_STRIP','` ==
known bug -- see: http://bugs.openembedded.org/Ticket/Display.html?id=257 There are several workarounds:
** inherit package in the offending bb files
** set INHERIT += "package_ipk debian" in your distro or local.conf file

== 5. I updated OE.db and now my builds are failing during the glibc compile, complaining about bad symbol definitions. What's wrong? ==

As of this writing, the version of glibc in the .dev branch of OE calls for a version of binutils it really shouldn't use. A patch has been applied to some DISTRO .confs which forces the "correct" version of binutils (<2.17) for the moment. But if the DISTRO .conf file you're building with isn't patched, a workaround is to add the following line to your local.conf file:

PREFERRED_VERSION_binutils-cross = "2.16"

then reset the glibc build with

bitbake glibc -c clean

and start from where you left off.

== 6. My build dies during the qemu-native section. What gives? ==
If the error is:
| ERROR: QEMU requires SDL or Cocoa for graphical output
| To build QEMU without graphical output configure with --disable-gfx-check
| Note that this will disable all output from the virtual graphics card.
| FATAL: oe_runconf failed
Then install SDL headers (apt-get install libsdl1.2-dev under Ubuntu/Debian).

Else another workaround: Install qemu from the distribution for your development computer, and include
ASSUME_PROVIDED +="qemu-native"
in your local.conf file.

== 7. Bitbake tells me to "Please set TARGET_OS directly, or choose a MACHINE or DISTRO that does so.", but my local.conf file already does. ==

Be sure you are not running bitbake as root. Doing so breaks Bitbake's use of chroot.

== 8. qemu crashes during generation of binary locales ==

Set ENABLE_BINARY_LOCALE_GENERATION = "0" in your local.conf. This is probably a x86_64 issue.

== 9. sanity checker complains "/proc/sys/vm/mmap_min_addr is not 0" on Ubuntu ==

Ubuntu Hardy Heron has this value set to 65536 by default.
see /etc/sysctl.conf content below
<pre><nowiki>
# protect bottom 64k of memory from mmap to prevent NULL-dereference
# attacks against potential future kernel security vulnerabilities.
# (Added in kernel 2.6.23.)
vm.mmap_min_addr = 65536
</nowiki></pre>

Since Wine suffers from the same feature, a temporary and permenant fix
is already known.
See this link (duh!) : http://wiki.winehq.org/PreloaderPageZeroProblem

Q: Why is this necessary? I'm using debian, and mmap_min_addr is 4096, but I run qemu all the time, and it seems to work fine.

= Debugging OE Builds =
OE is not perfect. Due to the size, complexity, rapid pace of development, and lack of maintainers, you will often be presented with an opportunity to debug OE builds :). Fortunately, OE is easy to debug once you know a few tricks:

== 1. Debugging tips ==
* learn to use interactive bitbake (`bitbake -i`)
* The [[BitBake]] `--verbose` option will print package dependencies. This is very useful when trying to determine why a package is being built.
* The [[BitBake]] `-D` option will increase debugging level. Note `-D -D` is also a valid option and can be used to determine what conf files are being used -- look for lines begining with conf.

== 2. How do I re-build a failing package? ==
There are several options:
* `bitbake -b <path to bb file>`
* `bitbake <package name>`
* start bitbake interactive mode (`bitbake -i`) and then run `build <package name>`

== 3. How do I clean a package? ==
There are several options:
* `bitbake -b <path to bb file> -c clean`
* `bitbake <package name> -c clean`
* start bitbake interactive mode (`bitbake -i`) and then run `clean <package name>`
You may also put several package names after the command e.g.
* `bitbake -c clean pack1 pack2 ...`
Sometimes you want to clean a particular package version from your build/tmp/work directory. In this case use
* for example `bitbake -c clean gcc-cross-initial-4.1.1`
Note: You have to use the package directory name here from your work directory without the trailing `-rx`. That means there is not an underscore before the package version but a simple dash.
The above is quite useful if you want to clean up a work directory from unwanted versions of the same package.

The ipk file in the directory deploy/ipk is not deleted when you perform a clean on a certain package. So make sure you manually rebuild the cleaned package in order to get an updated ipk or delete the ipk prior to a build.

== 4. What tasks are available for a package/recipe? ==
Building an OE package consists of a number of tasks. These tasks can be listed with the OE listtasks task. Each task can be run individually.

Example:

<pre>
bitbake -b <path to bb file> -c listtasks
NOTE: package matchbox-0.9.1: started
NOTE: package matchbox-0.9.1-r0: task do_listtasks: started
do_listtasks
do_compile
do_stage
do_build
do_mrproper
do_fetch
do_configure
do_clean
do_emit_manifest
do_populate_staging
do_package
do_unpack
do_install
do_showdata
do_patch
NOTE: package matchbox-0.9.1-r0: task do_listtasks: completed
NOTE: package matchbox-0.9.1: completed
Build statistics:
Attempted builds: 1
</pre>

== 5. How do I view the value of OE variables for a package? ==
* Use the [[BitBake]] command.
** `bitbake -e ../openembedded/recipes/meta/bootstrap-image.bb`
** `bitbake -e <package name>`
* Use the [[OpenEmbedded]] showdata command. Ex: `bitbake -b ../openembedded/recipes/meta/bootstrap-image.bb -c showdata`

== 6. How do I unpack ipk files? ==
ipk package files can be unpackaged with the `ar` command. Ex: `ar x <path to ipk file>` You can also inspect the files inside an ipk and get other information with the dpkg command if your distribution has it.

Category talk:FAQ

2010-05-26T13:18:51Z

Jhelwig: Undo revision 2314 by 212.235.107.114 (Talk)

BeagleBoard

2010-05-09T17:08:50Z

Jhelwig: Undo revision 2300 by 60.19.24.7 (Talk)

== Kernel Support in OE ==

=== Linux ===

OpenEmbedded offers more than one kernel for the BeagleBoard. All come with several patches but the support of the BeagleBoard hardware is not perfect yet.
The table summarizes the current status of hardware support. Please note that this applies to the kernels we have in OE only.

{| border="1" cellspacing="0" cellpadding="6" align="center"
! Boot
! USB OTG
! USB host
! DVI
! Audio out
! Audio in
! S-Video out
! MMC / SD
! RS232
! Flash
! DSP
! SGX
|-
| 2.6.27-r11
| style="background:yellow;" | host only
| style="background:green;" |
| style="background:green;" |
| style="background:yellow;" |
| style="background:red;" |
| style="background:red;" |
| style="background:green;" |
| style="background:green;" |
| style="background:green;" |
| style="background:green;" |
| style="background:green;" |
|-
| 2.6.28-r12
| style="background:green;" |
| style="background:green;" |
| style="background:green;" |
| style="background:green;" |
| style="background:green;" |
| style="background:green;" |
| style="background:green;" |
| style="background:green;" |
| style="background:green;" |
| style="background:green;" |
| style="background:green;" |
|-
|}

Currently 2.6.27 is the default kernel in OE. If you want to build 2.6.28 you can set PREFERRED_VERSION_linux-omap = "2.6.28" in your local.conf. Then build the kernel <code>bitbake virtual/kernel</code> or a filesystem that should include the kernel modules.
Another way to build the desired kernel is to point OE to the kernel bb directly.

[[Category: Machine]]

Talk:Stable

2010-05-05T13:46:42Z

Jhelwig: Spam removal.

Talk:BitBake

2010-05-02T14:07:54Z

Jhelwig: Spam removal.

Talk:Index.php/Documentation

2010-05-02T14:07:37Z

Jhelwig: Spam removal.

TSC

2010-04-19T16:45:25Z

Jhelwig: Undo revision 2282 by 67.202.107.22 (Talk)

=OE Technical Steering Committee=

The TSC consists of 5 people and will be elected by, and ultimately be answerable to, the members of the OE e.V.

= Members =

Graeme Gregory (XorA)
Koen Kooi
Chris Larson (kergoth)
Michael 'Mickey' Lauer (mickeyl)
Richard Purdie (RP)

= Responsibilities =

On a day-to-day basis the TSC will be responsible for making
tactical policy decisions, resolving disputes between contributors,
administering access control to the git tree, and generally promoting
good development practice.

= Decision Making =

Decisions are made where necessary by majority vote. Once a decision is made by
the technical steering committee, the decision should be respected as a democratic decision.

[[Category:Policy]]

User talk:Laibsch

2010-04-19T14:06:54Z

Jhelwig: Undo revision 2280 by 91.205.73.232 (Talk)

ToDo
* think about policy for allowing and denying access to certain pages and groups of pages
* [http://linuxtogo.org/~leggewie/index.php/Interwiki_links interwiki links] to bug tracker, etc.
* is mail working correctly? I don't seem to receive any. Maybe my addy is incorrect.

== Naming again ==

Hi Laibsch, your [http://wiki.openembedded.net/index.php?title=Devshell&curid=187&diff=1296&oldid=1223 change] is an example for additional work resulting from misunderstanding abbreviations by wiki users (see [[Category talk:Dev]]). For a casual user it is not clear what ''Dev'' stands for. ''Developer''? ''Development''? ''Device''? Once again i suggest to rename ambiguous pages and categories. -- [[User:Sledz|Sledz]] 07:58, 11 May 2009 (UTC)

: A wiki is a wiki and that is what it should remain being. The [[:Category:Dev]] page clearly states what it is about. No matter what you do, people will have different perceptions or plainly not read what is there. I think it is a question of overhead vs. flexibility. I choose flexibility to make users want to contribute to the wiki. The overhead is far less than the time we spent arguing about it. --[[User:Laibsch|Laibsch]] 12:08, 11 May 2009 (UTC)

PS: What about putting [[Openembedded:Help]] to the sidebar now?

== Header Level ==

Hi Laibsch, once again me, the nitpicker. ;-)

You [http://wiki.openembedded.net/index.php?title=Infrastructure&curid=158&diff=1345&oldid=1340 reverted] my header level fixup at the [[Infrastructure]] page. In MediaWiki applications it is common practise, that the page title itself is header level 1, so all subheaders should be level 2 (see e.g. Wikipedia.org). This clear structure is very helpful if you want to export the pages to other formats (e.g. PDF for printing). -- [[User:Sledz|Sledz]] 15:49, 17 May 2009 (UTC)

: I was unaware of this, but it looks like indeed Wikipedia follows this practice. Not sure if this wiki will be exported to PDF, but how would we do this? IOW, where would it make a practical difference? Until now, I just found it natural to start header level at 1. --[[User:Laibsch|Laibsch]] 20:38, 17 May 2009 (UTC)

:: For PDF export there are a lot of MediaWiki extensions e.g. [http://www.mediawiki.org/wiki/Extension:PDF_Writer PDF Writer] together with [http://www.mediawiki.org/wiki/Extension:Collection Collection] or [http://www.mediawiki.org/wiki/Extension:Pdf_Book PdfBook] and [http://www.mediawiki.org/wiki/Extension:Pdf_Export PdfExport]. And as said before header level 1 is used for the page title itself. -- [[User:Sledz|Sledz]] 15:41, 18 May 2009 (UTC)

Upgrading packages

2010-04-16T03:10:12Z

Jhelwig:

Please follow these steps when upgrading a package to a more recent version. This is not to be seen as dogma, but rather as best practice. There are basically two cases we need to consider:

# You do want to keep the version of the bb file that is in OE now (somebody else needs this particular version)
# You don't.

Make sure you add an appropriate entry in checksums.ini and run the file through contrib/source-checker/oe-checksums-sorter.py if the new version fetches new sources.

= You do not need to keep the last version of the package =

# Use "[http://www.kernel.org/pub/software/scm/git/docs/git-mv.html git-mv] packages/$pkg/$file_v1.bb packages/$pkg/$file_v2.bb" so that we don't accumulate unecessary cruft.
# make further changes to packages/$pkg/$file_v2.bb as appropriate.
# At the very minimum do a compilation test "bitbake $file" to make sure the new package does at least fetch and compile.
# inspect the output of "git diff packages/$pkg/". Is this really what you want to commit?
# Final step, publish your work. "git commit packages/$pkg/ && git push". Include conf/checksums.ini in your commit, if appropriate (see above).

= You do want to keep the last version of the package =

Same as above, except instead of the first step:

cp packages/$pkg/$file_v1.bb packages/$pkg/$file_v2.bb
git-add packages/$pkg/$file_v2.bb

= Removing recipes =

Although preventing the accumulation of cruft in the repository is good, you should take into account that distributions may be using a certain recipe and depend upon it. Therefore, before removing a recipe from the repository, do a grep in the 'conf/distro' directory. If the version you are going to remove is being explicitly used, send the respective patch to the development mailing list for 'RFC' first.

: This is too restrictive and I think above paragraph was added to this page without a directive from the core team who should have been the one to decide. preferred-om-2008-versions.inc looks down virtually all recipes. In essence, the above requirement for RFC translates into "all old versions have to accumulate in HEAD or an RFC for their removal sent". I don't think that is what we want. I will certainly not follow that like a slave for packages that I maintain (For example, I will update libassa in a minute to 3.5.0 without keeping 3.4.2 around and wasting my time on re-libtoolizing an obsolete version of a fringe package. Sorry). --[[User:Laibsch|Laibsch]] 22:07, 18 May 2009 (UTC)

[[Category:Policy]]

Mailing lists

2010-04-10T23:11:03Z

Jhelwig: Fix broken subscribe link for openembedded-commits

{| class="wikitable" border="2"
|-
||openembedded-devel@lists.openembedded.org || [http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel subscribe] || [http://thread.gmane.org/gmane.comp.handhelds.openembedded archive*]
|-
||openembedded-commits@lists.openembedded.org || [http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-commits subscribe] || [http://thread.gmane.org/gmane.comp.handhelds.openembedded.scm archive*]
|-
||openembedded-issues@lists.openembedded.org || || [http://lists.linuxtogo.org/pipermail/openembedded-issues/ archive]
|-
||openembedded-users@lists.openembedded.org || || [http://thread.gmane.org/gmane.comp.handhelds.openembedded.user archive*]
|-
||openembedded-stablebranch@lists.openembedded.org || || [http://thread.gmane.org/gmane.comp.handhelds.openembedded.stable archive*]
|}

<nowiki>
* denotes a searchable archive
</nowiki>

Last three mailing lists were removed from our server.

[[Category:Community]]

Getting started with OE-Classic

2010-04-03T18:46:21Z

Jhelwig:

= Setting up the toolchain and doing a build =

Before starting to configure your OE installation by following the instructions on this page make sure you have read [[OEandYourDistro|how OE fits in with your host distribution]] and the [[RequiredSoftware|required software for compilation]].

== Directory Structure ==
The base directory of your Openembedded environment (<nowiki>/stuff/</nowiki>) is the location where sources will be checked out (or unpacked).

* You must choose a location with '''no symlinks above it'''

* If you work in a chrooted environment and have ccache installed it is highly recommended to 'su - <username>' after you have chrooted. Compilation may fail because ccache needs a valid <nowiki>$HOME</nowiki>, which is usually set when using a user account. It is recommended that ccache is not installed on systems used to build OpenEmbedded as it has been known to introduce other subtle build failures.

To create the directory structure:

<pre><nowiki>
$ mkdir -p /stuff/build/conf
$ cd /stuff/
</nowiki></pre>

== Obtaining BitBake ==
To start using OE, you must first obtain the build tool it needs: <nowiki>bitbake</nowiki>

It is recommended to run bitbake without installing it, as a sibling directory of <nowiki>openembedded/</nowiki> and <nowiki>build/</nowiki> directories. Indeed, as bitbake is written in python it does not need to be compiled. You'll just have to set the PATH variable so that the [[BitBake]] tools are accessible (see [[#Setup the environment|Setup the environment]] section).

===Getting a working bitbake===

Bitbake switched from a svn repository to a git one, and the former is stuck at version 1.8.13, so when you try to build you may face an error: "Bitbake version 1.8.16 is required and version 1.8.13 was found". In that case please fetch released version or use git repository.

Which version is safe to use? Last release one is always working. When OE changes require newer version of BitBake metadata is changed and you will get message like above.

One note for those who want to play with development versions of BitBake - Python 2.6 may be required by newer versions. This can be a problem for some Linux distributions.

Basically the easier and faster solution (at the moment I'm writing) is to get release one.

wget http://download.berlios.de/bitbake/bitbake-1.8.18.tar.gz

Laibsch also provides a [http://oss.leggewie.org/oe/deb/bitbake_1.8.18-1_all.deb deb-package for bitbake 1.8.18] that should work in all current Ubuntu and Debian releases.

===Using releases===

Visit [http://developer.berlios.de/projects/bitbake/ BitBake homepage] and download tarball with latest release. For normal usage we suggest using 1.8.x (stable branch) versions. Unpack it to '''/stuff/bitbake/'''.

== Obtaining OpenEmbedded using Git ==

''Note: ''Once upon a time OpenEmbedded was using Monotone for version control. If you have an OE Monotone repository on your computer, you should replace it with the Git repository.

''Note: ''These are only brief instructions. For a longer description about using Git with OpenEmbedded refer to [[Git]] and [[GitPhraseBook]].

The OpenEmbedded project resides in a Git repository. You can find it at ''git://git.openembedded.org/openembedded''.

Web interface is: http://cgit.openembedded.org/

To obtain Openembedded:
# Install git
# Go to the base directory of your OpenEmbedded environment
$ cd /stuff/
# Checkout the repository
$ git clone git://git.openembedded.org/openembedded

or for the firewall challenged try
$ git clone http://repo.or.cz/r/openembedded.git

This is the data you'll be using for all the work.

=== Updating OpenEmbedded ===
The .dev branch of OE is updated very frequently (as much as several times an hour). The distro branches are not updated as much but still fairly often. It seems good practice to update your OE tree at least daily. To do this, run
$ git pull
(note: this must be done in the directory created by the checkout of openembedded. On this page, this directory is <tt>/stuff/openembedded</tt>, but my checkout generated a directory <tt>/stuff/openembedded</tt>. Check the name of your subdir, and use the name on your machine in the following examples)

== Create local configuration ==
It's now time to create your local configuration.
While you could copy the default local.conf.sample like this:

<pre><nowiki>
$ cd /stuff/
$ cp openembedded/conf/local.conf.sample build/conf/local.conf
$ vi build/conf/local.conf
</nowiki></pre>

It is actually recommended to start smaller and keep local.conf.sample in the background and add entries from there step-by-step as you understand and need them. Please, do not just edit build/conf/local.conf.sample but actually READ it (read it and then edit).

For building a .dev branch, in your <nowiki>local.conf</nowiki> file, you should have at least the following three entries. Example for the Angstrom distribution and the Openmoko gta01 machine:
<pre><nowiki>
BBFILES = "/stuff/openembedded/recipes/*/*.bb"
DISTRO = "angstrom-2008.1"
MACHINE = "om-gta01"
</nowiki></pre>

If you choose to install OE in your home directory, modify local.conf to refer to the OE paths as /home/<username>/ rather than ~/. It does not find the *.bb packages otherwise.

== Setup the environment ==
One of the four command sets below will need to be run every time you open a terminal for development. (You can automate this in ~/.profile, /etc/profile, or perhaps use a script to set the necessary variables for using [[BitBake]].)

If you followed the recommendation above to use [[BitBake]] from Git:
<pre><nowiki>
$ export BBPATH=/stuff/build:/stuff/openembedded
$ export PATH=/stuff/bitbake/bin:$PATH
</nowiki></pre>

If you installed [[BitBake]]:
<pre><nowiki>
$ export BBPATH=/stuff/build:/stuff/openembedded
</nowiki></pre>

Alternative syntax for those using the tcsh shell (e.g FreeBSD):
<pre><nowiki>
$ setenv PATH "/stuff/bitbake/bin:"$PATH
$ setenv BBPATH "/stuff/build:/stuff/openembedded:"$BBPATH
</nowiki></pre>

== Start building ==
The primary interface to the build system is the <nowiki>bitbake</nowiki> command (see the bitbake users manual). <nowiki>bitbake</nowiki> will download and patch stuff from the network, so it helps if you are on a well connected machine.

Note that you should issue all bitbake commands from inside of the <nowiki>build/</nowiki> directory, or you should override TMPDIR to point elsewhere (by default it goes to <nowiki>tmp/</nowiki> relative to the directory you run the tools in).

Here are some example invocations:

Building a single package (e.g. nano):

<pre><nowiki>
$ bitbake nano
</nowiki></pre>

Building package sets (e.g. task-base):

<pre><nowiki>
$ bitbake task-base
</nowiki></pre>

''Special note for'' <nowiki>task-base</nowiki>: you may need additional setup for building this very one task. More details in [[ZaurusKernels]]

Building a group of packages and deploying them into a rootfs image:

GPE:

<pre><nowiki>
$ bitbake x11-gpe-image
</nowiki></pre>

X11:

<pre><nowiki>
$ bitbake x11-image
</nowiki></pre>

OPIE:

<pre><nowiki>
$ bitbake opie-image
</nowiki></pre>

('''NOTE:''' kergoth says it will take around 10GB of disk space to build an opie or gpe image for one architecture. 
sledge says: You can reduce it to ~4GB by [[Advanced_configuration|INHERIT += "rm_work"]])

('''NOTE:''' if you are using your custom kernel - set "Use the ARM EABI to compile the kernel (AEABI)" option in "Kernel Features")

See the /stuff/openembedded/recipes/meta/ directory if you're curious about what meta/task and image targets exist.

Building a single package, bypassing the long parse step (and therefore its dependencies--use with care):

<pre><nowiki>
$ bitbake -b /stuff/openembedded/recipes/blah/blah.bb
</nowiki></pre>

See [[Useful targets]] for a description of some of the more useful meta-packages. You will typically need at least one of the base images (<nowiki>bootstrap-image</nowiki>, <nowiki>opie-image</nowiki> or <nowiki>gpe-image</nowiki>), and if and only if you're building for an [http://wiki.openzaurus.org/Main_Page OpenZaurus] target requiring an installer image (such as C3000), an additional <nowiki>pivotboot-image</nowiki>.

Output of the build process (temporary files, log files and the binaries) all ends up in the <nowiki>tmp</nowiki> directory. Most interesting is probably the <nowiki>tmp/work/</nowiki> directory. Just have a look around the [[DirectoryStructure]].

Images generated by building package groups like <nowiki>opie-image</nowiki> or <nowiki>pivotboot-image</nowiki> are placed in the <nowiki>tmp/deploy/images/</nowiki> directory. Individual ipkg packages are put in <nowiki>tmp/deploy/ipk</nowiki>.

== Adding Packages ==
# Create [[bbfile]].
# Try building it locally.
# Fix eventual problems.
# Send .[[bbfile]] or an [[OePatch]] to the [http://wiki.openembedded.net/index.php/Mailing_Lists openembedded-devel mailing list]. Please note that changes should comply with the [[Commit_Policy | commit policy]].

= Problems =
Try to solve problems first by checking that you have done everything right, that nothing has changed from this description and that you have the latest code (see [[GitPhraseBook]]). Look also in the log file (referenced in any error message you will receive). If you still have problems, try checking [[PossibleFailures]] and [http://www.openembedded.org/wiki/OeFaq#builderrors common build errors].
Above links are dead, you can try the [[:Category:FAQ]]. If problems persist, ask on [[IRC]] or in the [[Mailing lists|openembedded mailing list]].

The Openembedded metadata is changing constantly. This implies several things:

# Once you have a "known good" version that works well on your system, keep it! To update, clone a new copy; don't overwrite that working version until it's known to be safe.
# To resolve build problems, "git pull" is your good friend. Many times, the issues will already be fixed in the current tree.
# Not all metadata updates cause the local caches to update correctly. Sometimes you'll need to remove the ".../tmp" work directory and rebuild from scratch.
# Similar issues apply to the package sources you download.

= Portability issues =
Make sure to set <nowiki>TARGET_OS</nowiki> to something other than linux in local.conf if your host isn't linux.

GNU extensions to tools are often required. Symlink GNU patch, make, and cp (from fileutils), chmod, sed, find, tar, awk into your OE development path.

FreeBSD 4 users: Perl 5.0 is too old. A more recent perl must be available as <nowiki>/usr/bin/perl</nowiki>. Unfortunately just having more recent perl in the path isn't good enough. Some scripts are hard-coded for <nowiki>/usr/bin/perl</nowiki>. You can test for which perl you're using by typing perl -v. see /usr/ports/UPDATING for instructions on updating perl. Don't forget to do a use.perl port as instructed in /usr/ports/UPDATING

FreeBSD users: Set <nowiki>BUILD_OS</nowiki> in local.conf to freebsdN where N is your major version number. At least the cross gcc wants this.

FreeBSD users: The build process of glibc uses a very long command line at some places. Increase ARG_MAX to at least 131072, by editing /usr/sys/sys/syslimits.h and recompile your kernel (and reboot).

= Productivity notes =
Use the interactive bitbake mode ("bitbake -i") to speed up work when debugging or developing .bb files. Remember to run "parse" at the prompt first. Go!

If you want to save some compile time or are interested in additional tweaks to local.conf take a look at the [[Advanced configuration]] page.

[[Category:User]]