How to become a PTXdist Guru Based on the ... - Pengutronix

OSELAS.Support
OSELAS.Training
OSELAS.Development
OSELAS.Services
<strong>How</strong> <strong>to</strong> <strong>become</strong> a <strong>PTXdist</strong> <strong>Guru</strong>
<strong>Based</strong> on the OSELAS.BSP( )
Pengutronix Generic-arm
Pengutronix e. K.
Peiner Straße 6–8
31137 Hildesheim
+49 (0)51 21 / 20 69 17 – 0 (Fon)
+49 (0)51 21 / 20 69 17 – 55 55 (Fax)
info@pengutronix.de
© 2011 Pengutronix, Hildesheim – Rev. 1549/456

Contents
1 Welcome <strong>to</strong> the Embedded World 6
1.1 First Steps in the Embedded World . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2 From Server <strong>to</strong> Embedded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3 Linux = Embedded Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2 Getting a working Environment 8
2.1 Download Software Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2 <strong>PTXdist</strong> Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.1 Main Parts of <strong>PTXdist</strong> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.2 Extracting the Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2.3 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2.4 Configuring <strong>PTXdist</strong> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.3 Toolchains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.1 Using Existing Toolchains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.2 Building a Toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.3.3 Building the OSELAS.Toolchain for OSELAS.BSP-Pengutronix-Generic-2011.01.0 . . . . . 13
2.3.4 Protecting the Toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.3.5 Building Additional Toolchains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3 <strong>PTXdist</strong> User’s Manual 15
3.1 <strong>How</strong> does it work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1.1 <strong>PTXdist</strong>’s perception of the world . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1.2 <strong>PTXdist</strong>’s build process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.2 First steps with <strong>PTXdist</strong> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.2.1 Extracting the Board Support Package . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.2.2 Selecting a Userland Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.2.3 Selecting a Hardware Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.2.4 Selecting a Toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.2.5 Building the Root Filesystem Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.2.6 What we Got Now . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.2.7 Creating a Root Filesystem Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.2.8 Running all Parts in an emulated Environment (QEMU) . . . . . . . . . . . . . . . . . . . 21
3.3 Adapting the OSELAS.BSP-Pengutronix-Generic-2011.01.0 Project . . . . . . . . . . . . . . . . . 22
3.3.1 Working with Kconfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.3.2 Adapting Platform Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.3.3 Adapting Linux Kernel Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.3.4 Adapting Userland Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4 <strong>PTXdist</strong> Developer’s Manual 27
4.1 <strong>PTXdist</strong>’s direc<strong>to</strong>ry hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.1.1 Rule Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.1.2 Patch Series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.1.3 Runtime Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3

Contents
4.2 Adding new Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.2.1 Rule File Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.2.2 Make it Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.2.3 Advanced Rule Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.2.4 Patching Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.2.5 Creating Patches for a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.2.6 Modifying Au<strong>to</strong><strong>to</strong>olized Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.3 Adding binary only Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.3.1 Old style - single files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.3.2 New style - using archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.3.3 Creating a Rules File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5 <strong>PTXdist</strong> Reference 45
5.1 Variables Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5.1.1 PTXDIST_TOPDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5.1.2 PTXDIST_WORKSPACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5.1.3 PTXDIST_SYSROOT_CROSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5.1.4 PTXDIST_SYSROOT_HOST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5.1.5 PTXDIST_SYSROOT_TARGET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.1.6 CROSS_PATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.1.7 HOST_PATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.1.8 ROOTDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.1.9 PTXCONF_PLATFORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.1.10 PTXDIST_PLATFORMSUFFIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.1.11 PTXDIST_PLATFORMCONFIGDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.1.12 PTXDIST_PLATFORMDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.2 Rule File Macro Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.2.1 targetinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.2.2 <strong>to</strong>uch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.2.3 clean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.2.4 install_copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.2.5 install_tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.2.6 install_alternative . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.2.7 install_link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
5.2.8 install_archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
5.3 Rule file layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
5.3.1 Default stage rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5.3.2 Skipping a Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5.4 <strong>PTXdist</strong> parameter reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.4.1 Setup and Project Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.4.2 Build Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.4.3 Clean Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
6 Various Aspects of Daily Work 56
6.1 Using an External Kernel Source Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6.1.1 Cloning the Linux Kernel Source Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6.1.2 Configuring <strong>PTXdist</strong> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6.1.3 Configuring the <strong>PTXdist</strong> Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6.1.4 Work Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
6.2 Discovering Runtime Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
4

Contents
6.2.1 Dependencies on Shared Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
6.2.2 Dependencies on other Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
6.3 Debugging with CPU emulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.3.1 Running an Application made for a different Architecture . . . . . . . . . . . . . . . . . 59
6.3.2 Debugging an Application made for a different Architecture . . . . . . . . . . . . . . . . 59
6.4 Migration between Minor Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
6.4.1 Simple Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
6.5 Migration between Major Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
6.5.1 Basic Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
6.5.2 Adaption of Rules Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
6.5.3 <strong>PTXdist</strong>-1 Look and Feel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6.6 Software Installation and Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6.6.1 ipkg Usage in <strong>PTXdist</strong> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6.6.2 Packet Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
6.6.3 Au<strong>to</strong>matic Packet Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
6.6.4 The ipkg Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
6.7 Downloading Packages from the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
7 Document Revisions 66
8 Getting help 67
8.1 Mailing Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
8.1.1 About <strong>PTXdist</strong> in Particular . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
8.1.2 About Embedded Linux in General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
8.2 News Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
8.2.1 About Linux in Embedded Environments . . . . . . . . . . . . . . . . . . . . . . . . . . 67
8.2.2 About General Unix/Linux Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
8.3 Chat/IRC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
8.4 Commercial Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
5

1 Welcome <strong>to</strong> the Embedded World
1.1 First Steps in the Embedded World
Once upon in time, programming embedded systems was easy: all a developer needed when he wanted <strong>to</strong> start
a new product was a good <strong>to</strong>olchain, consisting of
• a compiler
• maybe an assembler
• probably an EPROM burning device
and things could start. After some more or less short time, every register of the CPU was known, a variety of
library routines had been developed and our brave developer was able <strong>to</strong> do his project with the more and more
well-known system. The controllers had legacy interfaces like RS232, i2c or SPI which connected them <strong>to</strong> the
outside world and the main difference between the controllers available on the market was the number of GPIO
pins, UARTS and memory ressources.
Things have changed. Hardware manufacturers have weakened the border between deeply embedded microcontrollers
– headless devices with just a few pins and very limited computing power – and full blown microprocessors.
System structures became much more complicated: where our good old controllers have had just some
interrupts with some small interrupt service routines, we <strong>to</strong>day need complicated generic interrupt infrastructures,
suitable for generic software frameworks. Where we’ve had some linearly mapped flash ROM and some
data RAM we <strong>to</strong>day have multi-stage-pipeline architectures, memory management units, virtual address spaces,
on-chip-memory, caches and other complicated units, which is not exactly what the embedded system developer
wants program every other day.
Entering embedded operating systems. Although there are still some processors out there (like the popular
ARM7TDMI based SoCs) which can be programmed the good old non-operating-system way with reasonable
effort, it in fact is becoming more and more difficult. On the other hand, legacy I/O interfaces like RS232 are increasingly
often replaced by modern plug-and-play aware communication channels: USB, FireWire (IEEE1394),
Ethernet & friends are more and more directly being integrated in<strong>to</strong> <strong>to</strong>day’s microcontroller hardware. Whereas
some of these interfaces can ”‘somehow”’ be handled the old controller-style way of writing software, the developer
following this way will not be able <strong>to</strong> address the security and performance issues which come up with the
modern network accessible devices.
During the last years, more and more of the small-scale companies which developed little embedded operating
systems have been pushed out of the market. Nearly no small company is able <strong>to</strong> support all the different interfaces,
communication stacks, development <strong>to</strong>ols and security issues out there. New interfaces and -variants
(like USB On-the-Go) are developed faster than operating system developers can supply the software for them.
The result is a consolidation of the market: <strong>to</strong>day we see that, besides niche products, probably only the largest
commercial embedded operating system suppliers will survive that development.
Only the largest commercial...? There is one exception: when the same situation came up in the ”mainstream”
computer market at the beginning of the 1990ies, people started <strong>to</strong> develop an alternative <strong>to</strong> the large commercial
operating systems: Linux. Linux did never start with a ready-<strong>to</strong>-use solution: people had a problem, searched
for a solution but didn’t find one. Then they started <strong>to</strong> develop one themselves, often several people did this
6

1 Welcome <strong>to</strong> the Embedded World
in parallel, and in a huge community based evolution mechanism the best solutions found their way in<strong>to</strong> the
Linux kernel, which over the time formed one of the most reliable and performant kernels available <strong>to</strong>day. This
”develop-and-evolute” mechanism has shown its effectiveness over and over again in the server and desk<strong>to</strong>p
market of <strong>to</strong>day.
1.2 From Server <strong>to</strong> Embedded
The fact that for most technical problems that might occur it may be possible <strong>to</strong> find somebody on the internet
who has already worked on the same or another very similar problem, was one of the major forces behind the
success s<strong>to</strong>ry of Embedded Linux.
Studies have shown that more than 70% of the embedded developers are not satisfied with a black-box operating
system: they want <strong>to</strong> adapt it <strong>to</strong> their needs, <strong>to</strong> their special hardware situation (which most times is Just Different
than anything available). Embedded projects are even more variegated than desk<strong>to</strong>p- or server projects, due <strong>to</strong>
the fact that there exist so many different embedded processors with lots of peripherals out there.
Linux has evolved from an i386 only operating system <strong>to</strong> a kernel running on nearly every modern 32 bit processor
available <strong>to</strong>day: x86, PowerPC, ARM, MIPS, m68k, cris, Super-H etc. The kernel supplies a hardware abstraction
layer which lets our brave embedded developer once again concentrate on his very special problem, not on
handling negligibilities like memory management.
But Linux is only half of the s<strong>to</strong>ry. Besides the kernel, a Linux based embedded system consists of a ”userland”:
a filesystem, containing all the small <strong>to</strong>ols which form a small Unix system. Only the combination of the kernel
and a Userland let’s the developer run ”normal” processes on his x86 development machine as well as on his
embedded target.
1.3 Linux = Embedded Linux
Whereas the mainstream developers were always able <strong>to</strong> use normal Linux distributions like SuSE, RedHat, Mandrake
or Debian as a base for their applications, things are different for embedded systems.
Due <strong>to</strong> the restricted ressources these systems normally have, distributions have <strong>to</strong> be small and should only
contain those things that are needed for the application. Today’s mainstream distributions cannot be installed
in less than 100 MiB without major loss of functionality. Even Debian, probably <strong>to</strong>day the most cus<strong>to</strong>mizable
mainstream distribution, cannot be shrunk below this mark without for example losing the packet management,
which is an essential feature of using a distribution at all.
Additionally, source code for industrial systems has <strong>to</strong> be
• auditable and
• reproducable.
Embedded developers usually want <strong>to</strong> know what’s in their systems – be it that they have <strong>to</strong> support their software
for a long time span (something like 10-15 years are usual product lifetimes in au<strong>to</strong>mation applications) or that
they have such a special scenario that they have <strong>to</strong> maintain their integrated source of their Userland themselves.
Entering <strong>PTXdist</strong>.
7

2 Getting a working Environment
2.1 Download Software Components
In order <strong>to</strong> follow this manual, some software archives are needed. There are several possibilities how <strong>to</strong> get
these: either as part of an evaluation board package or by downloading them from the Pengutronix web site.
The central place for OSELAS related documentation is http://www.oselas.com. This website provides all required
packages and documentation (at least for software components which are available <strong>to</strong> the public).
To build OSELAS.BSP-Pengutronix-Generic-2011.01.0, the following archives have <strong>to</strong> be available on the development
host:
• ptxdist-2011.01.0.tar.bz2
• OSELAS.BSP-Pengutronix-Generic-2011.01.0.tar.gz
• OSELAS.Toolchain-1.99.3.7.tar.bz2
If they are not available on the development system yet, it is necessary <strong>to</strong> get them.
2.2 <strong>PTXdist</strong> Installation
The <strong>PTXdist</strong> build system can be used <strong>to</strong> create a root filesystem for embedded Linux devices. In order <strong>to</strong> start
development with <strong>PTXdist</strong> it is necessary <strong>to</strong> install the software on the development system.
This chapter provides information about how <strong>to</strong> install and configure <strong>PTXdist</strong> on the development host.
2.2.1 Main Parts of <strong>PTXdist</strong>
The most important software component which is necessary <strong>to</strong> build an OSELAS.BSP( ) board support package
is the ptxdist <strong>to</strong>ol. So before starting any work we’ll have <strong>to</strong> install <strong>PTXdist</strong> on the development host.
<strong>PTXdist</strong> consists of the following parts:
The ptxdist Program: ptxdist is installed on the development host during the installation process. ptxdist is
called <strong>to</strong> trigger any action, like building a software packet, cleaning up the tree etc. Usually the ptxdist
program is used in a workspace direc<strong>to</strong>ry, which contains all project relevant files.
A Configuration System: The config system is used <strong>to</strong> cus<strong>to</strong>mize a configuration, which contains information
about which packages have <strong>to</strong> be built and which options are selected.
Patches: Due <strong>to</strong> the fact that some upstream packages are not bug free – especially with regard <strong>to</strong> cross compilation
– it is often necessary <strong>to</strong> patch the original software. <strong>PTXdist</strong> contains a mechanism <strong>to</strong> au<strong>to</strong>matically
apply patches <strong>to</strong> packages. The patches are bundled in<strong>to</strong> a separate archive. Nevertheless, they are necessary
<strong>to</strong> build a working system.
8

2 Getting a working Environment
Package Descriptions: For each software component there is a “recipe” file, specifying which actions have <strong>to</strong> be
done <strong>to</strong> prepare and compile the software. Additionally, packages contain their configuration sniplet for
the config system.
Toolchains: <strong>PTXdist</strong> does not come with a pre-built binary <strong>to</strong>olchain. Nevertheless, <strong>PTXdist</strong> itself is able <strong>to</strong>
build <strong>to</strong>olchains, which are provided by the OSELAS.Toolchain() project. More in-deep information about
the OSELAS.Toolchain() project can be found here: http://www.pengutronix.de/oselas/<strong>to</strong>olchain/
index_en.html
Board Support Package This is an optional component, mostly shipped aside with a piece of hardware. There
are various BSP available, some are generic, some are intended for a specific hardware.
2.2.2 Extracting the Sources
To install <strong>PTXdist</strong>, at least two archives have <strong>to</strong> be extracted:
ptxdist-2011.01.0.tar.bz2 The <strong>PTXdist</strong> software itself
ptxdist-2011.01.0-projects.tgz Generic projects (optional), can be used as a starting point for self-built projects.
The <strong>PTXdist</strong> packet has <strong>to</strong> be extracted in<strong>to</strong> some temporary direc<strong>to</strong>ry in order <strong>to</strong> be built before the installation,
for example the local/ direc<strong>to</strong>ry in the user’s home. If this direc<strong>to</strong>ry does not exist, we have <strong>to</strong> create it and
change in<strong>to</strong> it:
$ cd
$ mkdir local
$ cd local
Next step is <strong>to</strong> extract the archive:
$ tar -xjf ptxdist-2011.01.0.tar.bz2
and if required the generic projects:
$ tar -xzf ptxdist-2011.01.0-projects.tgz
If everything goes well, we now have a <strong>PTXdist</strong>-2011.01.0 direc<strong>to</strong>ry, so we can change in<strong>to</strong> it:
$ cd ptxdist-2011.01.0
$ ls -lF
<strong>to</strong>tal 532
-rw-r--r-- 1 jb users 18361 Jan 6 14:50 COPYING
-rw-r--r-- 1 jb users 3865 Jan 6 14:50 CREDITS
-rw-r--r-- 1 jb users 115540 Jan 6 14:50 ChangeLog
-rw-r--r-- 1 jb users 57 Jan 6 14:50 INSTALL
-rw-r--r-- 1 jb users 2228 Jan 6 14:50 Makefile.in
-rw-r--r-- 1 jb users 4196 Jan 6 14:50 README
-rw-r--r-- 1 jb users 691 Jan 6 14:50 REVISION_POLICY
-rw-r--r-- 1 jb users 63019 Jan 6 14:50 TODO
-rwxr-xr-x 1 jb users 28 Jan 6 14:50 au<strong>to</strong>gen.sh
drwxr-xr-x 2 jb users 4096 Jan 6 14:50 bin
drwxr-xr-x 9 jb users 4096 Jan 6 14:50 config
-rwxr-xr-x 1 jb users 213205 Jan 6 16:29 configure
-rw-r--r-- 1 jb users 12539 Jan 6 14:50 configure.ac
drwxr-xr-x 10 jb users 4096 Jan 6 14:50 generic
drwxr-xr-x 162 jb users 4096 Jan 6 14:50 patches
9

2 Getting a working Environment
drwxr-xr-x 2 jb users 4096 Jan 6 14:50 platforms
drwxr-xr-x 4 jb users 4096 Jan 6 14:50 plugins
drwxr-xr-x 6 jb users 32768 Jan 6 14:50 rules
drwxr-xr-x 8 jb users 4096 Jan 6 14:50 scripts
drwxr-xr-x 2 jb users 4096 Jan 6 14:50 tests
2.2.3 Prerequisites
Before <strong>PTXdist</strong> can be installed it has <strong>to</strong> be checked if all necessary programs are installed on the development
host. The configure script will s<strong>to</strong>p if it discovers that something is missing.
The <strong>PTXdist</strong> installation is based on GNU au<strong>to</strong><strong>to</strong>ols, so the first thing <strong>to</strong> be done now is <strong>to</strong> configure the packet:
$ ./configure
This will check your system for required components <strong>PTXdist</strong> relies on. If all required components are found the
output ends with:
[...]
checking whether /usr/bin/patch will work... yes
configure: creating ./config.status
config.status: creating Makefile
config.status: creating scripts/ptxdist_version.sh
config.status: creating rules/ptxdist-version.in
ptxdist version 2011.01.0 configured.
Using ’/usr/local’ for installation prefix.
Report bugs <strong>to</strong> ptxdist@pengutronix.de
Without further arguments <strong>PTXdist</strong> is configured <strong>to</strong> be installed in<strong>to</strong> /usr/local, which is the standard location
for user installed programs. To change the installation path <strong>to</strong> anything non-standard, we use the --prefix argument
<strong>to</strong> the configure script. The --help option offers more information about what else can be changed for
the installation process.
The installation paths are configured in a way that several <strong>PTXdist</strong> versions can be installed in parallel. So if an
old version of <strong>PTXdist</strong> is already installed there is no need <strong>to</strong> remove it.
One of the most important tasks for the configure script is <strong>to</strong> find out if all the programs <strong>PTXdist</strong> depends on are
already present on the development host. The script will s<strong>to</strong>p with an error message in case something is missing.
If this happens, the missing <strong>to</strong>ols have <strong>to</strong> be installed from the distribution befor re-running the configure script.
When the configure script is finished successfully, we can now run
$ make
All program parts are being compiled, and if there are no errors we can now install <strong>PTXdist</strong> in<strong>to</strong> it’s final location.
In order <strong>to</strong> write <strong>to</strong> /usr/local, this step has <strong>to</strong> be performed as user root:
$ sudo make install
[enter password]
[...]
10

2 Getting a working Environment
If we don’t have root access <strong>to</strong> the machine it is also possible <strong>to</strong> install <strong>PTXdist</strong> in<strong>to</strong> some other direc<strong>to</strong>ry with
the --prefix option. We need <strong>to</strong> take care that the bin/ direc<strong>to</strong>ry below the new installation dir is added <strong>to</strong> our
$PATH environment variable (for example by exporting it in ˜/.bashrc).
The installation is now done, so the temporary folder may now be removed:
$ cd ../../
$ rm -fr local
2.2.4 Configuring <strong>PTXdist</strong>
When using <strong>PTXdist</strong> for the first time, some setup properties have <strong>to</strong> be configured. Two settings are the most
important ones: Where <strong>to</strong> s<strong>to</strong>re the source packages and if a proxy must be used <strong>to</strong> gain access <strong>to</strong> the world wide
web.
Run <strong>PTXdist</strong>’s setup:
$ ptxdist setup
Due <strong>to</strong> <strong>PTXdist</strong> is working with sources only, it needs various source archives from the world wide web. If these
archives are not present on our host, <strong>PTXdist</strong> starts the wget command <strong>to</strong> download them on demand.
Proxy Setup
To do so, an internet access is required. If this access is managed by a proxy wget command must be adviced <strong>to</strong>
use it. <strong>PTXdist</strong> can be configured <strong>to</strong> advice the wget command au<strong>to</strong>matically: Navigate <strong>to</strong> entry Proxies and enter
the required addresses and ports <strong>to</strong> access the proxy in the form:
://:
Source Archive Location
Whenever <strong>PTXdist</strong> downloads source archives it s<strong>to</strong>res these archives in a project local manner. If we are working
with more than one project, every project would download its own required archives. To share all source archives
between all projects <strong>PTXdist</strong> can be configured <strong>to</strong> use only one archive direc<strong>to</strong>ry for all projects it handles: Navigate
<strong>to</strong> menu entry Source Direc<strong>to</strong>ry and enter the path <strong>to</strong> the direc<strong>to</strong>ry where <strong>PTXdist</strong> should s<strong>to</strong>re archives <strong>to</strong>
share between projects.
Generic Project Location
If we already installed the generic projects we should also configure <strong>PTXdist</strong> <strong>to</strong> know this location. If we already
did so, we can use the command ptxdist projects <strong>to</strong> get a list of available projects and ptxdist clone <strong>to</strong> get a
local working copy of a shared generic project.
Navigate <strong>to</strong> menu entry Project Searchpath and enter the path <strong>to</strong> projects that can be used in such a way. Here
we can configure more than one path, each part can be delemited by a colon. For example for <strong>PTXdist</strong>’s generic
projects and our own previous projects like this:
/usr/local/lib/ptxdist-2011.01.0/projects:/office/my_projects/ptxdist
Leave the menu and s<strong>to</strong>re the configuration. <strong>PTXdist</strong> is now ready for use.
11

2 Getting a working Environment
2.3 Toolchains
Before we can start building our first userland we need a cross <strong>to</strong>olchain. On Linux, <strong>to</strong>olchains are no monolithic
beasts. Most parts of what we need <strong>to</strong> cross compile code for the embedded target comes from the GNU Compiler
Collection, gcc. The gcc packet includes the compiler frontend, gcc, plus several backend <strong>to</strong>ols (cc1, g++, ld etc.)
which actually perform the different stages of the compile process. gcc does not contain the assembler, so we
also need the GNU Binutils package which provides lowlevel stuff.
Cross compilers and <strong>to</strong>ols are usually named like the corresponding host <strong>to</strong>ol, but with a prefix – the GNU target.
For example, the cross compilers for ARM and powerpc may look like
• arm-softfloat-linux-gnu-gcc
• powerpc-unknown-linux-gnu-gcc
With these compiler frontends we can convert e.g. a C program in<strong>to</strong> binary code for specific machines. So for
example if a C program is <strong>to</strong> be compiled natively, it works like this:
$ gcc test.c -o test
To build the same binary for the ARM architecture we have <strong>to</strong> use the cross compiler instead of the native one:
$ arm-softfloat-linux-gnu-gcc test.c -o test
Also part of what we consider <strong>to</strong> be the ”<strong>to</strong>olchain” is the runtime library (libc, dynamic linker). All programs
running on the embedded system are linked against the libc, which also offers the interface from user space
functions <strong>to</strong> the kernel.
The compiler and libc are very tightly coupled components: the second stage compiler, which is used <strong>to</strong> build
normal user space code, is being built against the libc itself. For example, if the target does not contain a hardware
floating point unit, but the <strong>to</strong>olchain generates floating point code, it will fail. This is also the case when the
<strong>to</strong>olchain builds code for i686 CPUs, whereas the target is i586.
So in order <strong>to</strong> make things working consistently it is necessary that the runtime libc is identical with the libc the
compiler was built against.
<strong>PTXdist</strong> doesn’t contain a pre-built binary <strong>to</strong>olchain. Remember that it’s not a distribution but a development
<strong>to</strong>ol. But it can be used <strong>to</strong> build a <strong>to</strong>olchain for our target. Building the <strong>to</strong>olchain usually has only <strong>to</strong> be done
once. It may be a good idea <strong>to</strong> do that over night, because it may take several hours, depending on the target
architecture and development host power.
2.3.1 Using Existing Toolchains
If a <strong>to</strong>olchain is already installed which is known <strong>to</strong> be working, the <strong>to</strong>olchain building step with <strong>PTXdist</strong> may be
omitted.
The OSELAS.BoardSupport() Packages shipped for <strong>PTXdist</strong> have been tested with the OSE-
LAS.Toolchains() built with the same <strong>PTXdist</strong> version. So if an external <strong>to</strong>olchain is being used
which isn’t known <strong>to</strong> be stable, a target may fail. Note that not all compiler versions and combinations
work properly in a cross environment.
Every OSELAS.BoardSupport() Package checks for its OSELAS.Toolchain it’s tested against, so using a different
<strong>to</strong>olchain vendor requires an additional step:
Open the OSELAS.BoardSupport() Package menu with:
12

2 Getting a working Environment
$ ptxdist platformconfig
and navigate <strong>to</strong> architecture ---> <strong>to</strong>olchain and check for specific <strong>to</strong>olchain vendor. Clear this entry <strong>to</strong>
disable the <strong>to</strong>olchain vendor check.
Preconditions an external <strong>to</strong>olchain must meet:
• it shall be built with the configure option --with-sysroot pointing <strong>to</strong> its own C libraries.
• it should not support the multilib feature as this may confuse <strong>PTXdist</strong> which libraries are <strong>to</strong> select for the
root filesystem
If we want <strong>to</strong> check if our <strong>to</strong>olchain was built with the --with-sysroot option, we just run this simple command:
$ my<strong>to</strong>olchain-gcc -v 2>&1 | grep with-sysroot
If this command does not output anything, this <strong>to</strong>olchain was not built with the --with-sysroot option and
cannot be used with <strong>PTXdist</strong>.
2.3.2 Building a Toolchain
<strong>PTXdist</strong> handles <strong>to</strong>olchain building as a simple project, like all other projects, <strong>to</strong>o. So we can download the
OSELAS.Toolchain bundle and build the required <strong>to</strong>olchain for the OSELAS.BoardSupport() Package.
A <strong>PTXdist</strong> project generally allows <strong>to</strong> build in<strong>to</strong> some project defined direc<strong>to</strong>ry; all OSELAS.Toolchain projects
that come with <strong>PTXdist</strong> are configured <strong>to</strong> use the standard installation paths mentioned below.
All OSELAS.Toolchain projects install their result in<strong>to</strong> /opt/OSELAS.Toolchain-1.99.3/.
Usually the /opt direc<strong>to</strong>ry is not world writeable. So in order <strong>to</strong> build our OSELAS.Toolchain
in<strong>to</strong> that direc<strong>to</strong>ry we need <strong>to</strong> use a root account <strong>to</strong> change the permissions. <strong>PTXdist</strong> detects
this case and asks if we want <strong>to</strong> run sudo <strong>to</strong> do the job for us. Alternatively we can enter:
mkdir /opt/OSELAS.Toolchain-1.99.3
chown /opt/OSELAS.Toolchain-1.99.3
chmod a+rwx /opt/OSELAS.Toolchain-1.99.3.
We recommend <strong>to</strong> keep this installation path as <strong>PTXdist</strong> expects the <strong>to</strong>olchains at /opt. Whenever we go <strong>to</strong> select
a platform in a project, <strong>PTXdist</strong> tries <strong>to</strong> find the right <strong>to</strong>olchain from data read from the platform configuration
settings and a <strong>to</strong>olchain at /opt that matches <strong>to</strong> these settings. But that’s for our convenience only. If we decide
<strong>to</strong> install the <strong>to</strong>olchains at a different location, we still can use the <strong>to</strong>olchain parameter <strong>to</strong> define the <strong>to</strong>olchain <strong>to</strong>
be used on a per project base.
2.3.3 Building the OSELAS.Toolchain for OSELAS.BSP-Pengutronix-Generic-2011.01.0
To compile and install an OSELAS.Toolchain we have <strong>to</strong> extract the OSELAS.Toolchain archive, change in<strong>to</strong> the
new folder, configure the compiler in question and start the build.
The required compiler <strong>to</strong> build the OSELAS.BSP-Pengutronix-Generic-2011.01.0 board support package is
arm-v4t-linux-gnueabi_gcc-4.3.2_glibc-2.8_binutils-2.18_kernel-2.6.27-sanitized
13

2 Getting a working Environment
So the steps <strong>to</strong> build this <strong>to</strong>olchain are:
In order <strong>to</strong> build any of the OSELAS.Toolchains, the host must provide the <strong>to</strong>ol fakeroot. Otherwise
the message bash: fakeroot: command not found will occur and the build s<strong>to</strong>ps.
$ tar xf OSELAS.Toolchain-1.99.3.7.tar.bz2
$ cd OSELAS.Toolchain-1.99.3.7
$ ptxdist select ptxconfigs/¿
arm-v4t-linux-gnueabi_gcc-4.3.2_glibc-2.8_binutils-2.18_kernel-2.6.27-sanitized.ptxconfig
$ ptxdist go
At this stage we have <strong>to</strong> go <strong>to</strong> our boss and tell him that it’s probably time <strong>to</strong> go home for the day. Even on
reasonably fast machines the time <strong>to</strong> build an OSELAS.Toolchain is something like around 30 minutes up <strong>to</strong> a
few hours.
Measured times on different machines:
• Single Pentium 2.5 GHz, 2 GiB RAM: about 2 hours
• Turion ML-34, 2 GiB RAM: about 1 hour 30 minutes
• Dual Athlon 2.1 GHz, 2 GiB RAM: about 1 hour 20 minutes
• Dual Quad-Core-Pentium 1.8 GHz, 8 GiB RAM: about 25 minutes
Another possibility is <strong>to</strong> read the next chapters of this manual, <strong>to</strong> find out how <strong>to</strong> start a new project.
When the OSELAS.Toolchain project build is finished, <strong>PTXdist</strong> is ready for prime time and we can continue with
our first project.
2.3.4 Protecting the Toolchain
All <strong>to</strong>olchain components are built with regular user permissions. In order <strong>to</strong> avoid accidential changes in the
<strong>to</strong>olchain, the files should be set <strong>to</strong> read-only permissions after the installation has finished successfully. It is also
possible <strong>to</strong> set the file ownership <strong>to</strong> root. This is an important step for reliability, so it is highly recommended.
2.3.5 Building Additional Toolchains
The OSELAS.Toolchain-1.99.3.7 bundle comes with various predefined <strong>to</strong>olchains. Refer the ptxconfigs/ folder
for other definitions. To build additional <strong>to</strong>olchains we only have <strong>to</strong> clean our current <strong>to</strong>olchain project, removing
the current selected_ptxconfig link and creating a new one.
$ ptxdist clean
$ rm selected_ptxconfig
$ ptxdist select ptxconfigs/any_other_<strong>to</strong>olchain_def.ptxconfig
$ ptxdist go
All <strong>to</strong>olchains will be installed side by side architecture dependent in<strong>to</strong> direc<strong>to</strong>ry
/opt/OSELAS.Toolchain-1.99.3/architecture_part.
Different <strong>to</strong>olchains for the same architecture will be installed side by side version dependent in<strong>to</strong> direc<strong>to</strong>ry
/opt/OSELAS.Toolchain-1.99.3/architecture_part/version_part.
14

3 <strong>PTXdist</strong> User’s Manual
This chapter should give any newbie the information he/she needs <strong>to</strong> be able <strong>to</strong> handle any embedded Linux
projects based on <strong>PTXdist</strong>. Also the advanced user may find new valueable information.
3.1 <strong>How</strong> does it work?
<strong>PTXdist</strong> supports various aspects of the daily work <strong>to</strong> develop, deploy and maintain an embedded Linux based
project.
Figure 3.1: Objectives in a project
The most important part is the development. For this project phase, <strong>PTXdist</strong> provides features <strong>to</strong> ensure reproducibility
and verifiability.
3.1.1 <strong>PTXdist</strong>’s perception of the world
<strong>PTXdist</strong> works project centric. A <strong>PTXdist</strong> project contains all information and files <strong>to</strong> populate any kind of target
system with all required software components.
• Specific configuration for
– Bootloader
– Kernel
– Userland (root filesystem)
• Adapted files (or generic ones) for runtime configuration
• Patches for all kind of components (<strong>to</strong> fix bugs or improve features)
15

3 <strong>PTXdist</strong> User’s Manual
Some of these information or files are coming from the <strong>PTXdist</strong> base installation (patches for example), but also
can be part of the project itself. By this way, <strong>PTXdist</strong> can be adapted <strong>to</strong> any kind of requirement.
Most users are fine with the information and files the <strong>PTXdist</strong> base installation provides. Development of <strong>PTXdist</strong>
is done in a way <strong>to</strong> find default settings most user can work with. But advanced users can still adapt <strong>to</strong> their special
needs.
As stated above, a <strong>PTXdist</strong> project consists of all required parts, some of these parts are separated by design:
<strong>PTXdist</strong> separates a platform configuration from userland configuration (root filesystem). So, platforms can share
a common userland configuration, but use a specific kernel configuration in their own platform configuration.
Collecting various platforms in<strong>to</strong> one single project should help <strong>to</strong> maintain such projects. But some platforms
do need special userland (think about graphic/non graphic platforms). To be able <strong>to</strong> also collect this requirement
in<strong>to</strong> one single project, so called collections are supported. With this feature, a user can configure a full featured
main userland, reduced via a collection by some components for a specific platform where it makes no sense <strong>to</strong>
build and ship them.
<strong>PTXdist</strong> can handle the following project variations:
• one hardware platform, one userland configuration (common case)
• one hardware platform, various userland configurations
• various hardware platforms, one userland configuration (common case)
• various hardware platforms, one userland configuration, various collections
• various hardware platforms, various userland configuration
• various hardware platforms, various userland configuration, various collections
3.1.2 <strong>PTXdist</strong>’s build process
When <strong>PTXdist</strong> is building one part (we call it a package)of the whole project, it is divided in<strong>to</strong> up <strong>to</strong> six stages:
get The package will be obtained from its source (downloaded from the web for example)
extract The package archive gets extracted and patched if a patch set for this package exists
prepare Many packages can be configured in various ways. If supported, this stage does the configuration in a
way defined in the menu (project specific)
compile The package gets built.
install The package installs itself in<strong>to</strong> a project local direc<strong>to</strong>ry. This step is important at least for libraries (other
packages may depend on)
targetinstall Relevant parts of the package will be used <strong>to</strong> build an IPKG archive and the root filesystem
For each single package, one so called rule file exists, describing the steps <strong>to</strong> be done in each stage shown above
(refer section 5.3 for further details).
Due <strong>to</strong> the get stage, <strong>PTXdist</strong> needs a working internet connection <strong>to</strong> download an archive currently not existing
on the development host. But there are ways <strong>to</strong> prevent <strong>PTXdist</strong> from doing so (refer <strong>to</strong> section 2.2.4).
3.2 First steps with <strong>PTXdist</strong>
<strong>PTXdist</strong> works as a console command <strong>to</strong>ol. Everything we want <strong>PTXdist</strong> <strong>to</strong> do, we have <strong>to</strong> enter as a command.
But it’s always the same base command:
16

3 <strong>PTXdist</strong> User’s Manual
Figure 3.2: The build process
$ ptxdist
To run different functions, this command must be extended by parameters <strong>to</strong> define the function we want <strong>to</strong> run.
If we are unsure what parameter must be given <strong>to</strong> obtain a special function, we run it with the parameter help.
$ ptxdist help
This will output all possible parameters ans subcommands and their meaning.
As the list we see is very long, let’s explain the major parameters usually needed for daily usage:
menu This starts a dialog based frontend for those who do not like typing commands. It will gain us access <strong>to</strong>
the most common parameters <strong>to</strong> configure and build a <strong>PTXdist</strong> project.
menuconfig Starts the Kconfig based project configura<strong>to</strong>r for the current selected userland configuration. This
menu will give us access <strong>to</strong> various userland components that the root filesystem of our target should
consist of.
platformconfig Starts the Kconfig based platform configura<strong>to</strong>r. This menu lets us set up all target specific settings.
Major parts are:
• Toolchain (architecture and revision)
• boot loader
• root filesystem image type
• Linux kernel (revision)
Note: A <strong>PTXdist</strong> project can consist of more than one platform configuration at the same time.
kernelconfig Runs the standard Linux kernel Kconfig <strong>to</strong> configure the kernel for the current selected platform.
To run this feature, the kernel must be already set up for this platform.
17

3 <strong>PTXdist</strong> User’s Manual
menuconfig collection If multiple platforms are sharing one userland configuration, collections can define a
subset of all selected packages for specific platforms. This is an advanced feature, rarely used.
<strong>to</strong>olchain Sets up the path <strong>to</strong> the <strong>to</strong>olchain used <strong>to</strong> compile the current selected platform. Without an additional
parameter, <strong>PTXdist</strong> tries <strong>to</strong> guess the <strong>to</strong>olchain from platform settings. To be successful, <strong>PTXdist</strong> depends
on the OSELAS.Toolchains installed <strong>to</strong> the /opt direc<strong>to</strong>ry.
If <strong>PTXdist</strong> wasn’t able <strong>to</strong> au<strong>to</strong>detect the <strong>to</strong>olchain, an additional parameter can be given <strong>to</strong> provide the
path <strong>to</strong> the compiler, assembler, linker and so on.
select Used <strong>to</strong> select the current userland configuration, which is only required if there is no selected_ptxconfig
in the project’s main direc<strong>to</strong>ry. This parameter needs the path <strong>to</strong> a valid ptxconfig. It will generate a soft
link called selected_ptxconfig in the project’s main direc<strong>to</strong>ry.
platform Used <strong>to</strong> select the current platform configuration, which is only required if there is no selected_platformconfig
in the project’s main direc<strong>to</strong>ry. This parameter needs the path <strong>to</strong> a valid
platformconfig. It will generate a soft link called selected_platformconfig in the project’s main direc<strong>to</strong>ry.
collection Used <strong>to</strong> select the current collection configuration, which is only required in special cases. This parameter
needs the path <strong>to</strong> a valid collection. It will generate a soft link called selected_collection in the
project’s main direc<strong>to</strong>ry. This is an advanced feature, rarely used.
go The mostly used command. This will start <strong>to</strong> build everything <strong>to</strong> get all the project defined software parts.
Also used <strong>to</strong> rebuild a part after its configuration was changed.
images Used at the end of a build <strong>to</strong> create an image from all userland packages <strong>to</strong> deploy the target (its flash
for example or its hard disk).
setup Mostly run once per <strong>PTXdist</strong> revision <strong>to</strong> set up global paths and the <strong>PTXdist</strong> behavior.
All these commands depending on various files a <strong>PTXdist</strong> based project provides. So, running the commands
make only sense in direc<strong>to</strong>rys that contains a <strong>PTXdist</strong> based project. Otherwise <strong>PTXdist</strong> gets confused and confuses
the user with funny error messages.
To show the usage of some listed major subcommands, we are using a generic <strong>PTXdist</strong> based project.
3.2.1 Extracting the Board Support Package
In order <strong>to</strong> work with a <strong>PTXdist</strong> based project we have <strong>to</strong> extract the archive first.
$ tar -zxf OSELAS.BSP-Pengutronix-Generic-2011.01.0.tar.gz
$ cd OSELAS.BSP-Pengutronix-Generic-2011.01.0
<strong>PTXdist</strong> is project centric, so now after changing in<strong>to</strong> the new direc<strong>to</strong>ry we have access <strong>to</strong> all valid components.
<strong>to</strong>tal 32
-rw-r--r-- 1 jb users 1060 Jul 1 16:33 ChangeLog
-rw-r--r-- 1 jb users 741 Jul 1 15:12 README
drwxr-xr-x 5 jb users 4096 Jul 1 15:17 configs
drwxr-xr-x 3 jb users 4096 Jul 1 16:51 documentation
drwxr-xr-x 5 jb users 4096 Jul 1 15:12 local_src
drwxr-xr-x 4 jb users 4096 Jul 1 15:12 patches
drwxr-xr-x 5 jb users 4096 Jul 1 15:12 projectroot
drwxr-xr-x 3 jb users 4096 Jul 1 15:12 rules
18

3 <strong>PTXdist</strong> User’s Manual
Notes about some of the files and direc<strong>to</strong>ries listed above:
ChangeLog Here you can read what has changed in this release. Note: This file does not always exist.
documentation If this BSP is one of our OSELAS BSPs, this direc<strong>to</strong>ry contains the Quickstart you are currenly
reading in.
configs A multiplatform BSP contains configurations for more than one target. This direc<strong>to</strong>ry contains the respective
platform configuration files.
projectroot Contains files and configuration for the target’s runtime. A running GNU/Linux system uses many
text files for runtime configuration. Most of the time, the generic files from the <strong>PTXdist</strong> installation will fit
the needs. But if not, cus<strong>to</strong>mized files are located in this direc<strong>to</strong>ry.
rules If something special is required <strong>to</strong> build the BSP for the target it is intended for, then this direc<strong>to</strong>ry contains
these additional rules.
patches If some special patches are required <strong>to</strong> build the BSP for this target, then this direc<strong>to</strong>ry contains these
patches on a per package basis.
tests Contains test scripts for au<strong>to</strong>mated target setup.
Next we will build the OSELAS.BSP-Pengutronix-Generic-2011.01.0 <strong>to</strong> show some of <strong>PTXdist</strong>’s main features.
3.2.2 Selecting a Userland Configuration
First of all we have <strong>to</strong> select a userland configuration. This step defines what kind of applications will be built for
the hardware platform. The OSELAS.BSP-Pengutronix-Generic-2011.01.0 comes with a predefined configuration
we select in the following step:
$ ptxdist select configs/ptxconfig
info: selected ptxconfig:
’configs/ptxconfig’
3.2.3 Selecting a Hardware Platform
Before we can build this BSP, we need <strong>to</strong> select one of the possible platforms <strong>to</strong> build for. In this case we want <strong>to</strong>
build for the Versatilepb:
$ ptxdist platform configs/arm-qemu-2011.01.0/platformconfig
info: selected platformconfig:
’configs/arm-qemu-2011.01.0/platformconfig’
Note: If you have installed the OSELAS.Toolchain() at its default location, <strong>PTXdist</strong> should already have detected
the proper <strong>to</strong>olchain while selecting the platform. In this case it will output:
found and using <strong>to</strong>olchain:
’/opt/OSELAS.Toolchain-1.99.3/arm-v4t-linux-gnueabi/¿
gcc-4.3.2-glibc-2.8-binutils-2.18-kernel-2.6.27-sanitized/bin’
If it fails you can continue <strong>to</strong> select the <strong>to</strong>olchain manually as mentioned in the next section. If this au<strong>to</strong>detection
was successful, we can omit the steps of the section and continue <strong>to</strong> build the BSP.
19

3 <strong>PTXdist</strong> User’s Manual
3.2.4 Selecting a Toolchain
If not au<strong>to</strong>matically detected, the last step in selecting various configurations is <strong>to</strong> select the <strong>to</strong>olchain <strong>to</strong> be used
<strong>to</strong> build everything for the target.
$ ptxdist <strong>to</strong>olchain /opt/OSELAS.Toolchain-1.99.3/arm-v4t-linux-gnueabi/¿
gcc-4.3.2-glibc-2.8-binutils-2.18-kernel-2.6.27-sanitized/bin
3.2.5 Building the Root Filesystem Content
Now everything is prepared for <strong>PTXdist</strong> <strong>to</strong> compile the BSP. Starting the engines is simply done with:
$ ptxdist go
<strong>PTXdist</strong> does now au<strong>to</strong>matically find out from the selected_ptxconfig and selected_platformconfig files which
packages belong <strong>to</strong> the project and starts compiling their targetinstall stages (that one that actually puts the compiled
binaries in<strong>to</strong> the root filesystem). While doing this, <strong>PTXdist</strong> finds out about all the dependencies between
the packages and builds them in correct order.
3.2.6 What we Got Now
After building the project, we find even more sub direc<strong>to</strong>ries in our project.
platform-versatilepb/build-cross Contains all packages sources compiled <strong>to</strong> run on the host and handle target
architecture dependend things.
platform-versatilepb/build-host Contains all packages sources compiled <strong>to</strong> run on the host and handle architecture
independend things.
platform-versatilepb/build-target Contains all package sources compiled for the target architecure.
platform-versatilepb/images Generated files for the target can be found here: Kernel image and root filesystem
image.
platform-versatilepb/packages Location for alle individual packages in ipk format.
platform-versatilepb/sysroot-target Contains everything target architecture dependend (libraries, header files
and so on).
platform-versatilepb/sysroot-cross Contains everything that is host specific but must handle target architecture
data.
platform-versatilepb/sysroot-host Contains everything that is only host specific.
platform-versatilepb/root Target’s root filesystem image. This direc<strong>to</strong>ry can be mounted as an NFS root for
example.
Note: Due <strong>to</strong> only root can create device nodes and the build system must be run as a non root user, there is
no device node present in this image. At least /dev/console, /dev/null and /dev/zero should exist. Create
them as user root manually in order <strong>to</strong> use this direc<strong>to</strong>ry as an NFS root.
platform-versatilepb/root-debug Target’s root filesystem image. The difference <strong>to</strong> root/ is, all programs and
libraries in this direc<strong>to</strong>ry still have their debug information present. This direc<strong>to</strong>ry is intended <strong>to</strong> be used
as system root for a debugger. To be used by the debugger, you should setup your debugger with
set solib-absolute-prefix /root-debug
20

3 <strong>PTXdist</strong> User’s Manual
platform-versatilepb/state Building every package is divided on<strong>to</strong> stages. And stages of one package can depend
on stages of other packages. In order <strong>to</strong> handle this correctly, this direc<strong>to</strong>ry contains timestamp files
about finished stages.
This are the generated files:
platform-versatilepb/logfile Every run of <strong>PTXdist</strong> will add its output <strong>to</strong> this file. If something fails, this file can
help <strong>to</strong> find the cause.
3.2.7 Creating a Root Filesystem Image
After we have built the root filesystem content, we can make an image, which can be flashed <strong>to</strong> the target system
or copied on some kind of disk media. To do so, we just run
$ ptxdist images
<strong>PTXdist</strong> now extracts the content of priorly created *.ipk packages <strong>to</strong> a temporary direc<strong>to</strong>ry and generates an
image out of it. <strong>PTXdist</strong> supports following image types:
• hd.img: contains bootloader, kernel and root files in an ext2 partition. Mostly used for X86 target systems.
• root.jffs2: root files inside a jffs2 filesystem.
• uRamdisk: a u-boot loadable Ramdisk
• initrd.gz: a traditional initrd RAM disk <strong>to</strong> be used as initrdramfs by the kernel
• root.ext2: root files inside an ext2 filesystem.
• root.squashfs: root files inside a squashfs filesystem.
• root.tgz: root files inside a plain gzip compressed tar ball.
All these files can be found in platform-versatilepb/images.
3.2.8 Running all Parts in an emulated Environment (QEMU)
The OSELAS.BSP-Pengutronix-Generic-2011.01.0 is prepared <strong>to</strong> give every user a chance <strong>to</strong> run the results of the
previous steps even in the absense of real hardware. All we need is a working QEMU on our development host.
Simply run
$ ./configs/arm-qemu-2011.01.0/run
This will start QEMU in full system emulation mode and runs the previously built kernel which then uses the
generated disk image <strong>to</strong> bring up a full Linux based system.
The running system uses a serial device for its communication. QEMU forwards this emulated device <strong>to</strong> the
current development host console. So, we can watch the starting kernel’s output and log in on this system.
Note: Log in as user ’root’ with no password (just enter).
Also a telnet deamon is running in this emulation. QEMU is configured <strong>to</strong> forward the standard telnet port 23 of
the emulated system <strong>to</strong> host’s port 4444. To connect <strong>to</strong> the emulated system, we can just run a
$ telnet localhost 4444
Trying 127.0.0.1...
Connected <strong>to</strong> localhost.
Escape character is ’]’.
21

3 <strong>PTXdist</strong> User’s Manual
ptx login: root
root@ptx:~
Leaving the emulated environment happens by entering the key sequence CTRL-A X in the development host
console.
3.3 Adapting the OSELAS.BSP-Pengutronix-Generic-2011.01.0 Project
Handling a fully prepared <strong>PTXdist</strong> project is easy. But everything is fixed <strong>to</strong> the settings the developer selected.
We now want <strong>to</strong> adapt the OSELAS.BSP-Pengutronix-Generic-2011.01.0 project in a few simple settings.
3.3.1 Working with Kconfig
Whenever we modify our project, <strong>PTXdist</strong> is using Kconfig <strong>to</strong> manipulate the settings. Kconfig means kernel configura<strong>to</strong>r
and was mainly developed <strong>to</strong> configure the Linux kernel itself. But it is easy <strong>to</strong> adapt, <strong>to</strong> use and so
popular that more and more projects are using Kconfig for their purposes. <strong>PTXdist</strong> is one of them.
What is Kconfig
It is a user interface <strong>to</strong> select given resources in a convenient way. The resources that we can select are given in
simple text files. It uses a powerful ”language” in these text files <strong>to</strong> organize them in a hierarchical manner, solves
challenges like resource dependencies, supports help and search features. <strong>PTXdist</strong> uses all of these features.
Kconfig supports a text based user interface by using the ncurses library <strong>to</strong> manipulate the screen content and
should work on nearly all host systems.
For example running <strong>PTXdist</strong>’s menuconfig subcommand in this way
$ ptxdist menuconfig
will show the following console output
Navigate in Kconfig menu (select, search, ...)
To navigate through the configuration tree, we are using the arrow keys. Up and down navigates vertically in the
menu entries. Right and left navigates between Select, Exit and Help (in the bot<strong>to</strong>m part of our visual screen).
To enter one of the menus, we navigate <strong>to</strong> this entry <strong>to</strong> highlight it and press the Enter key. To leave it, we select
Exit and press the Enter key again. There are shortcuts available, instead of pressing the Enter key <strong>to</strong> enter a menu
we also can press alt-s and <strong>to</strong> leave a menu alt-e. Also an ESC double hit leaves any menu we are in.
To select a menu entry, we use the Space key. This will <strong>to</strong>ggle the selection. Or, <strong>to</strong> be more precise and faster, we
use the key y <strong>to</strong> select an entry, and key n <strong>to</strong> deselect it.
To get help for a specific menu <strong>to</strong>pic, we navigate vertically <strong>to</strong> highlight it and horizontally <strong>to</strong> select the Help entry.
Then we can press Enter <strong>to</strong> see the help.
To search for specific keywords, we press the / key and enter a word. Kconfig then lists all occurences of this word
in all menus.
22

3 <strong>PTXdist</strong> User’s Manual
Figure 3.3: Main userland configuration menu
Meaning of visual feedbacks in Kconfig
• Submenus <strong>to</strong> enter are marked with a trailing --->
Note: Some submenus are also marked with a leading bracket [ ]. To enter them we first must select/enable
them [*]
• Entries with a list of selectable alternatives are also marked with a trailing --->
• Entries we can select are marked with a leading empty bracket [ ]
• Entries that are already selected are marked with a leading filled bracket [*]
• Entries that are selected due <strong>to</strong> dependencies in<strong>to</strong> other selected entries are marked with a leading -*-
• Some entries need a free text <strong>to</strong> enter, they are marked with leading brackets () and the free text in it
Menus and submenus in Kconfig (sectioning)
There are dozens of entries in the <strong>PTXdist</strong> configuring menus. To handle them, they are divided and separated
in<strong>to</strong> logical units.
The main building blocks in the userland configuration menu are:
• Host Options: Some parts of the project are build host relevant only. For example <strong>PTXdist</strong> can build the
DDD debugger <strong>to</strong> debug applications running on the target.
23

3 <strong>PTXdist</strong> User’s Manual
• Root Filesystem: Settings <strong>to</strong> arrange target’s root filesystem and <strong>to</strong> select the main C runtime library
• Applications: Everything we like <strong>to</strong> run on your target.
The main building blocks in the platform configuration menu are:
• Architecture: Basic settings, like the main and sub architecture the target system uses, the <strong>to</strong>olchain <strong>to</strong> be
used <strong>to</strong> build everything and some other architecture dependent settings.
• Linux kernel: Which kernel revision and kernel configuration should be used
• Bootloader: Which bootloader (if any) should be built in the project
• The kind of image <strong>to</strong> populate a root filesystem in<strong>to</strong> the target system
The main building blocks in the board setup configuration menu are:
• Network: Network settings for the target
• Host: Host setup <strong>to</strong> be able <strong>to</strong> reach the target system
At this point it could be useful <strong>to</strong> walk <strong>to</strong> the whole menus and their submenus <strong>to</strong> get an idea about the amount
of features and applications <strong>PTXdist</strong> currently supports.
3.3.2 Adapting Platform Settings
Some parts of the OSELAS.BSP-Pengutronix-Generic-2011.01.0 project are platform specific (in contrast <strong>to</strong> the
userland configuration that could be shared between platforms). We now want <strong>to</strong> change the used Linux kernel
of our current arm-qemu-2011.01.0 platform. It comes with a default linux-2.6.32 and we want <strong>to</strong> change it <strong>to</strong> a
more recent linux-2.6.37.
To do so, we run:
$ ptxdist menuconfig platform
In this Kconfig dialogue we navigate <strong>to</strong> the entry:
[*] Linux kernel --->
(2.6.32) kernel version
and replace the 2.6.32 value by the 2.6.37 value. Now we leave the menu and save the new settings.
A Linux kernel needs a configuration for being built correctly. The OSELAS.BSP-Pengutronix-Generic-2011.01.0
project comes with a prepared configuration in the file configs/arm-qemu-2011.01.0/kernelconfig-2.6.32 for
the 2.6.32 kernel.
It is always a good idea <strong>to</strong> start with a known-<strong>to</strong>-work kernel configuration. So, for this example, we are using a
different known-<strong>to</strong>-work kernel configuration in the configs/arm-qemu-2011.01.0/kernelconfig-2.6.37 file for
our new 2.6.37 kernel.
3.3.3 Adapting Linux Kernel Settings
In this section we want <strong>to</strong> show how <strong>to</strong> change some Linux kernel settings of our OSELAS.BSP-Pengutronix-
Generic-2011.01.0project.
First of all, we run
24

3 <strong>PTXdist</strong> User’s Manual
$ ptxdist menuconfig kernel
This command will start the kernel’s Kconfig. For this example we want <strong>to</strong> enable USB host support in the kernel.
To do so, we navigate <strong>to</strong>:
Device Drivers --->
[ ] USB support --->
< > Support for Host-side USB
< > OHCI HCD support
Note: All the listed empty [ ] and < > above must be activated <strong>to</strong> get all submenu entries.
We leave the menu and save the new kernel configuration.
To start building a new kernel with the new configuration, we again run:
$ ptxdist go
This builds or re-builds the kernel, because we changed its settings.
Note: If nothing was changed, ptxdist go also will do nothing.
When <strong>PTXdist</strong> has finished its job, the new bootable kernel can be found at platform-versatilepb/images/linuximage.
To boot it again in the QEMU emulation, the hard disk image must be re-created with:
$ ptxdist images
$ ./configs/arm-qemu-2011.01.0/run
The emulated system should now start with a 2.6.37 based kernel with USB support.
3.3.4 Adapting Userland Settings
After changing some platform and kernel settings, we are now reaching the most interesting area: Userland.
In the userland area we can enable and use all the applications and services <strong>PTXdist</strong> provides. Many of them are
working out of the box when enabled and executed on the target side. Some need additional runtime configuration,
but <strong>PTXdist</strong> comes with most common configurations for such packages.
In this simple example, we want <strong>to</strong> add the missing head command <strong>to</strong> our target’s shell. Assuming we forgot <strong>to</strong>
enable this command, we get:
$ ./configs/arm-qemu-2011.01.0/run
ptx login: root
login[xxx]: root login on ’ttyS0’
root@ptx:~ head /etc/fstab
-sh: head: not found
To change this, we first run:
$ ptxdist menuconfig
The additional command we want <strong>to</strong> enable is provided by the Busybox package. So we navigate <strong>to</strong>:
25

3 <strong>PTXdist</strong> User’s Manual
Shell & Console Tools --->
-*- busybox --->
Coreutils --->
[ ] head
After activating the [ ] head entry, we leave the menu and save the new configuration.
Once again, a
$ ptxdist go
will build or re-build the busybox package due <strong>to</strong> its configuration change.
And also once again, after finishing its job, the following commands let us test the new command:
$ ptxdist images
$ ./configs/arm-qemu-2011.01.0/run
Log in on the emulated system and simply check with a:
ptx login: root
login[xxx]: root login on ’ttyS0’
root@ptx:~ head /etc/fstab
#
# /etc/fstab
#
# special filesystems
proc /proc proc defaults 0 0
debugfs /sys/kernel/debug debugfs defaults,noau<strong>to</strong> 0 0
devpts /dev/pts devpts defaults 0 0
none /tmp tmpfs defaults,mode=1777,uid=0,gid=0 0 0
none /sys sysfs defaults 0 0
We are done now. These simple examples should give the users a quick feeling how things are working in <strong>PTXdist</strong>
and how <strong>to</strong> modify them. Adapting this generic BSP <strong>to</strong> a different platform with nearly the same features as our
reference platforms is possible with this knowledge.
But most of the time, a user needs more detailed adaptions <strong>to</strong> be able <strong>to</strong> fit all requirements of the new platform.
At this point of time we are no longer ordinary users of <strong>PTXdist</strong>, we <strong>become</strong> developers now.
So, right now its time <strong>to</strong> read the <strong>PTXdist</strong> Developer’s Manual
26

4 <strong>PTXdist</strong> Developer’s Manual
This chapter will show all (or most) of the details of how <strong>PTXdist</strong> works.
• where are the files s<strong>to</strong>red that <strong>PTXdist</strong> uses when building packages
• how patching works
• where is <strong>PTXdist</strong> fetching a package’s runtime configuration files from
• how <strong>to</strong> control a package’s build stages
• how <strong>to</strong> add new packages
4.1 <strong>PTXdist</strong>’s direc<strong>to</strong>ry hierarchy
Note: Referenced direc<strong>to</strong>ries are meant relative <strong>to</strong> the <strong>PTXdist</strong> main installation location (if not otherwise stated).
If not configured differently, this main path is /usr/local/lib/ptxdist-2011.01.0
4.1.1 Rule Files
When building a single package, <strong>PTXdist</strong> needs the information on how <strong>to</strong> handle the package, i.e. on how <strong>to</strong> get
it from the source up <strong>to</strong> what the target needs at runtime. This information is provided by a rule file per package.
<strong>PTXdist</strong> collects all rule files in its rules/ direc<strong>to</strong>ry. Whenever <strong>PTXdist</strong> builds something, all these rule files are
scanned at once. These rule files are global rule files, valid for all projects. <strong>PTXdist</strong> uses a mechanism <strong>to</strong> be able
<strong>to</strong> add or replace specific rule files on a per project base. If a rules/ direc<strong>to</strong>ry exists in the current project, its
content is scanned <strong>to</strong>o. These project local rule files are used in addition <strong>to</strong> the global rule files or – if they are
using the same name as a global rule file – replacing the global rule file.
The replacing mechanism can be used <strong>to</strong> extend or adapt packages for specific project requirements. Or it can
be used for bug fixing by backporting rule files from more recent <strong>PTXdist</strong> revisions <strong>to</strong> projects that are stuck <strong>to</strong>
an older <strong>PTXdist</strong> revision for maintenance only.
4.1.2 Patch Series
There are many packages in the wild that are not cross build aware. They fail compiling some files, use wrong
include paths or try <strong>to</strong> link against host libraries. To be sucessful in the embedded world, these types of failures
must be fixed. If required, <strong>PTXdist</strong> provides such fixes per package. They are organized in patch series and can
be found in the patches/ direc<strong>to</strong>ry within a subdirec<strong>to</strong>ry using the same name as the package itself.
<strong>PTXdist</strong> uses the utility patchor quilt<strong>to</strong> apply an existing patch series after extracting the archive. So, every patch
series contains a set of patches and one series file <strong>to</strong> define the order in which the patches must be applied.
Note: Patches can be compressed.
27

4 <strong>PTXdist</strong> Developer’s Manual
Besides the patches/ direc<strong>to</strong>ry at the main installation location, <strong>PTXdist</strong> searches two additional locations for a
patch series for the package in question.
One location is the project’s currently used platform direc<strong>to</strong>ry. If the currently used platform is located in
configs/arm-qemu-2011.01.0, <strong>PTXdist</strong> searches in ./configs/arm-qemu-2011.01.0/patches/.
If no patch series was found in the platform direc<strong>to</strong>ry, the next location <strong>PTXdist</strong> it searches for a patch series is
the main project direc<strong>to</strong>ry in ./patches/.
If both project local locations do not provide a patch series for the specific package, <strong>PTXdist</strong> falls back <strong>to</strong> the
patches/ direc<strong>to</strong>ry at its main installation location.
This search order can be used <strong>to</strong> use specific patch series for specific cases.
• platfom specific
• project specific
• common case
• bug fixing
The bug fixing case is used in accordance <strong>to</strong> a replacement of a rule file. If this was done due <strong>to</strong> a backport, and
the more recent <strong>PTXdist</strong> revision does not only exchange the rule file but also the patch series, this mechanism
ensures that both relevant parts can be updated in the project.
4.1.3 Runtime Configuration
Many packages are using runtime configuration files along with their executables and libraries. <strong>PTXdist</strong> provides
default configuration files for the most common cases. These files can be found in the generic/etc direc<strong>to</strong>ry and
they are using the same names as the ones at runtime (and their install direc<strong>to</strong>ry on the target side will also be
/etc).
But some of these default configuration files are empty, due <strong>to</strong> the absence of a common case. The project must
provide replacements of these files with a more useful content in every case where the (empty) default one does
not meet the target’s requirements.
<strong>PTXdist</strong> first searches the project local ./projectroot/etc direc<strong>to</strong>ry for a specific configuration file and falls back
<strong>to</strong> use the default one if none exists locally.
A popular example is the configuration file /etc/fstab. The default one coming with <strong>PTXdist</strong> works for the
most common cases. But if our project requires a special setup, we can just copy the default one <strong>to</strong> the local
./projectroot/etc/fstab, modify it and we are done. The next time <strong>PTXdist</strong> builds the root filesystem it will use
the local fstab instead of the global (default) one.
4.2 Adding new Packages
<strong>PTXdist</strong> provides a huge amount of applications sufficient for the most embedded use cases. But there is still
need for some fancy new packages. This section describes the steps and the background on how <strong>to</strong> intergrate
new packages in<strong>to</strong> the project.
At first a summary about possible application types which <strong>PTXdist</strong> can handle:
28

4 <strong>PTXdist</strong> Developer’s Manual
• host type: This kind of package is built <strong>to</strong> run on the build host. Most of the time such a package is needed
if another target relevant package needs <strong>to</strong> generate some data. For example the glib package depends
on its own <strong>to</strong> create some data. But if it is compiled for the target, it can’t do so. That’s why a host glib
package is required <strong>to</strong> provide these utilities runnable on the build host. It sounds strange <strong>to</strong> build a host
package, even if on the build host such utilities are already installed. But this way ensures that there are
no dependencies regarding the build host system.
• target type: This kind of package is built for the target.
• cross type: This kind of package is built for the build host, but creates architecture specific data for the
target.
• klibc type: This kind of package is built against klibc <strong>to</strong> be part of an initramfs for the target.
• src-au<strong>to</strong>conf-prog: This kind of package is built for the target. It is intended for development, as it does not
handle a released archive but a plain source project instead. Creating such a package will also on demand
create a small au<strong>to</strong><strong>to</strong>ols based source template project <strong>to</strong> give the developer an easy point <strong>to</strong> start. This
template is prepared <strong>to</strong> build a single executable program.
• src-au<strong>to</strong>conf-lib: This kind of package is built for the target. It is intended for development, as it does not
handle a released archive but a plain source project instead. Creating such a package will also on demand
create a small au<strong>to</strong><strong>to</strong>ols/lib<strong>to</strong>ol based source template project <strong>to</strong> give the developer an easy point <strong>to</strong> start.
This template is prepared <strong>to</strong> build a single shared library.
• src-au<strong>to</strong>conf-proglib: This kind of package is built for the target. It is intended for development, as it
does not handle a released archive but a plain source project instead. Creating such a package will also
on demand create a small au<strong>to</strong><strong>to</strong>ols/lib<strong>to</strong>ol based template project <strong>to</strong> give the developer an easy point
<strong>to</strong> start. This template is prepared <strong>to</strong> build a single shared library and a single executable program. The
program will be linked against the shared library.
• file: This kind of package is intended <strong>to</strong> add a few simple files in<strong>to</strong> the build process. We assume these
files do not need any processing, they are ready <strong>to</strong> use and only must present in the build process or at
runtime (HTML files for example). Refer the section 4.3 for further details on how <strong>to</strong> use it.
• src-make-prog: This kind of package is built for the target. Its intended for development, as it does not
handle a released archive but a plain source project instead. Creating such a package will also create a
simple makefile based template project the developen can use as a starting point for development.
• src-cmake-prog: This kind of package is built for the target. Its intended for developments based on the
cmake buildsystem. If the developen is going <strong>to</strong> develop a QT based application, this rule is prepared <strong>to</strong>
compile sources in accordance <strong>to</strong> the target libraries and their settings. Creating such a package will also
create a simple template project <strong>to</strong> be used as a starting point for development.
• font: This package is a helper <strong>to</strong> add X font files <strong>to</strong> the root filesystem. This package does not create
an additional IPKG, instead it adds the font <strong>to</strong> the existing font IPGK. This includes the generation of the
direc<strong>to</strong>ry index files, required by the Xorg framework <strong>to</strong> recognize the font file.
• src-linux-driver: This kind of package builds an out of tree kernel driver. It also creates a driver template
<strong>to</strong> give the developer an easy point <strong>to</strong> start.
• src-stellaris: This package is intended for development of firmware for standalone Cortex-M3 Stellaris
microcontrollers. These kind of microcontrollers are running without any operating systems most of the
time. It also creates a small firmware template <strong>to</strong> give the developer an easy point <strong>to</strong> start.
4.2.1 Rule File Creation
To create such a new package, we create a project local rules/ direc<strong>to</strong>ry first. Then we run
29

4 <strong>PTXdist</strong> Developer’s Manual
$ ptxdist newpackage
If we omit the , <strong>PTXdist</strong> will list all available package types.
In our first example, we want <strong>to</strong> add a new target type archive package. When running the
$ ptxdist newpackage target
command, <strong>PTXdist</strong> asks a few questions about this package. This information is the basic data <strong>PTXdist</strong> must
know about the package.
ptxdist: creating a new ’target’ package:
ptxdist: enter package name.......: foo
ptxdist: enter version number.....: 1.1.0
ptxdist: enter URL of basedir.....: http://www.foo.com/download/src
ptxdist: enter suffix.............: tar.gz
ptxdist: enter package author.....: My Name
ptxdist: enter package section....: project_specific
What we have <strong>to</strong> answer:
• package name: As this kind of package handles a source archive, the correct answer here is the basename
of the archive’s file name. If its full name is foo-1.1.0.tar.gz, then foo is the basename <strong>to</strong> enter here.
• version number: Most source archives are using a release or version number in their file name. If its full
name is foo-1.1.0.tar.gz, then 1.1.0 is the version number <strong>to</strong> enter here.
• URL of basedir: This URL tells <strong>PTXdist</strong> where <strong>to</strong> download the source archive from the web (if not already
done). If the full URL <strong>to</strong> download the archive is http://www.foo.com/download/src/foo-1.1.0.tar.gz,
the basedir part http://www.foo.com/download/src is <strong>to</strong> enter here.
• suffix: Archives are using various formats for distribution. <strong>PTXdist</strong> uses the suffix entry <strong>to</strong> select the matching
extraction <strong>to</strong>ol. If the archive’s full name is foo-1.1.0.tar.gz, then tar.gz is the suffix <strong>to</strong> enter here.
• package author: If we intend <strong>to</strong> contribute this new package <strong>to</strong> <strong>PTXdist</strong> mainline, we should add our name
here. This name will be used in the copyright note of the rule file and will also be added <strong>to</strong> the generated
ipkg. When you run ptxdist setup prior <strong>to</strong> this call, you can enter your name and your email address, so
<strong>PTXdist</strong> will use it as the default (very handy if you intend <strong>to</strong> add many new packages).
• package section: We can enter here the section name that should occur in the package’s menu entry. In
the first step we can leave the default name unchanged. It’s a string in the menu file only, so changing it
later on is still possible.
4.2.2 Make it Work
Generating the rule file is only one of the required steps <strong>to</strong> get a new package. The next steps <strong>to</strong> make it work
are <strong>to</strong> check if all stages are working as expected and <strong>to</strong> select the required parts <strong>to</strong> get them installed in the
target root filesystem. Also we must find a reasonable location where <strong>to</strong> add our new menu entry <strong>to</strong> configure
the package.
The generated skele<strong>to</strong>n starts <strong>to</strong> add the new menu entry in the main configure menu (if we left the section name
unchanged). Running ptxdist menuconfig will show it on <strong>to</strong>p of all other menus entries.
Note: To be able <strong>to</strong> implement all the other required steps for adding a new package, we first must enable the
package for building (fine tuning the menu can be the last step).
30

4 <strong>PTXdist</strong> Developer’s Manual
After enabling the menu entry, we can start <strong>to</strong> check the get and extract stage, calling them manually one after
another.
$ ptxdist get foo
---------------------------
target: foo-1.1.0.tar.gz
---------------------------
--2009-12-21 10:54:45-- http://www.foo.com/download/src/foo-1.1.0.tar.gz
Length: 291190 (284K) [application/x-gzip]
Saving <strong>to</strong>: ‘/global_src/foo-1.1.0.tar.gz.XXXXOGncZA’
100%[======================================>] 291,190 170K/s in 1.7s
2009-12-21 10:54:48 (170 KB/s) - ‘/global_src/foo-1.1.0.tar.gz’ saved [291190/291190]
This command should start <strong>to</strong> download the source archive. If it fails, we should check our network connection
and if the URL in use is correct.
$ ptxdist extract foo
-----------------------
target: foo.extract
-----------------------
extract: archive=/global_src/foo-1.1.0.tar.gz
extract: dest=/home/jbe/my_new_prj/build-target
PATCHIN: packet=foo-1.1.0
PATCHIN: dir=/home/jbe/my_new_prj/build-target/foo-1.1.0
PATCHIN: no patches for foo-1.1.0 available
Fixing up /home/jbe/my_new_prj/build-target/foo-1.1.0/configure
finished target foo.extract
In this example we expect an au<strong>to</strong><strong>to</strong>olized source package. E.g. <strong>to</strong> prepare the build, the archive comes with
a configure script. This is the default case for <strong>PTXdist</strong>. So, there is no need <strong>to</strong> modify the rule file and we can
simply run:
$ ptxdist prepare foo
-----------------------
target: foo.prepare
-----------------------
[...]
checking build system type... i686-host-linux-gnu
checking host system type... i586-unknown-linux-gnu
checking whether <strong>to</strong> enable maintainer-specific portions of Makefiles... no
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... /bin/mkdir -p
checking for gawk... gawk
checking whether make sets $(MAKE)... yes
checking for i586-unknown-linux-gnu-strip... i586-unknown-linux-gnu-strip
checking for i586-unknown-linux-gnu-gcc... i586-unknown-linux-gnu-gcc
31

4 <strong>PTXdist</strong> Developer’s Manual
checking for C compiler default output file name... a.out
[...]
configure: creating ./config.status
config.status: creating Makefile
config.status: creating ppa_pro<strong>to</strong>col/Makefile
config.status: creating config.h
config.status: executing depfiles commands
finished target foo.prepare
At this stage things can fail:
• The configure script is not cross compile aware
• The package depends on external components (libraries for example)
If the configure script is not cross compile aware, we are out of luck. We must patch the source archive in this
case <strong>to</strong> make it work. Refer <strong>to</strong> section 4.2.6 on how <strong>to</strong> use <strong>PTXdist</strong>’s features <strong>to</strong> simplify this task.
If the package depends on external components, these components might be already part of <strong>PTXdist</strong>. In this
case we just have <strong>to</strong> add this dependency in<strong>to</strong> the menu file and we are done. But if <strong>PTXdist</strong> cannot fulfill this
dependency, we also must add it as a separate package first.
If the prepare stage has finished successfully, the next step is <strong>to</strong> compile the package.
$ ptxdist compile foo
-----------------------
target: foo.compile
-----------------------
make[1]: Entering direc<strong>to</strong>ry ‘/home/jbe/my_new_prj/build-target/foo-1.1.0’
make all-recursive
make[2]: Entering direc<strong>to</strong>ry ‘/home/jbe/my_new_prj/build-target/foo-1.1.0’
make[3]: Entering direc<strong>to</strong>ry ‘/home/jbe/my_new_prj/build-target/foo-1.1.0’
[...]
make[3]: Leaving direc<strong>to</strong>ry ‘/home/jbe/my_new_prj/build-target/foo-1.1.0’
make[2]: Leaving direc<strong>to</strong>ry ‘/home/jbe/my_new_prj/build-target/foo-1.1.0’
make[1]: Leaving direc<strong>to</strong>ry ‘/home/jbe/my_new_prj/build-target/foo-1.1.0’
finished target foo.compile
At this stage things can fail:
• The build system is not cross compile aware (it tries <strong>to</strong> execute just created target binaries for example)
• The package depends on external components (libraries for example) not detected by configure
• Sources are ignoring the endianess of some architectures or using header files from the build host system
(from /usr/include for example)
• The linker uses libraries from the build host system (from /usr/lib for example) by accident
In all of these cases we must patch the sources <strong>to</strong> make them work. Refer <strong>to</strong> section 4.2.4 on how <strong>to</strong> use <strong>PTXdist</strong>’s
features <strong>to</strong> simplify this task.
In this example we expect the best case: Everything went fine, even for cross compiling. So, we can continue with
the next stage: install
32

4 <strong>PTXdist</strong> Developer’s Manual
$ ptxdist install foo
-----------------------
target: foo.install
-----------------------
make[1]: Entering direc<strong>to</strong>ry ‘/home/jbe/my_new_prj/build-target/foo-1.1.0’
make[2]: Entering direc<strong>to</strong>ry ‘/home/jbe/my_new_prj/build-target/foo-1.1.0’
make[3]: Entering direc<strong>to</strong>ry ‘/home/jbe/my_new_prj/build-target/foo-1.1.0’
test -z ”/usr/bin” /bin/mkdir -p ”/home/jbe/my_new_prj/build-target/foo-1.1.0/usr/bin”
/usr/bin/install -c ’foo’ ’/home/jbe/my_new_prj/build-target/foo-1.1.0/usr/bin/foo’
make[3]: Leaving direc<strong>to</strong>ry ‘/home/jbe/my_new_prj/build-target/foo-1.1.0’
make[2]: Leaving direc<strong>to</strong>ry ‘/home/jbe/my_new_prj/build-target/foo-1.1.0’
make[1]: Leaving direc<strong>to</strong>ry ‘/home/jbe/my_new_prj/build-target/foo-1.1.0’
finished target foo.install
----------------------------
target: foo.install.post
----------------------------
finished target foo.install.post
This install stage does not install anything <strong>to</strong> the target root filesystem. It is mostly intended <strong>to</strong> install libraries
that other programs should link against later on.
The last stage – targetinstall – is the one that defines the package’s components <strong>to</strong> be forwarded <strong>to</strong> the target’s
root filesystem. Due <strong>to</strong> the absence of a generic way, this is the task of the developer. So, at this point of time we
must run our favourite edi<strong>to</strong>r and modify our new rule file ./rules/foo.make.
The skele<strong>to</strong>n for the targetinstall stage looks like this:
# ----------------------------------------------------------------------------
# Target-Install
# ----------------------------------------------------------------------------
$(STATEDIR)/foo.targetinstall:
@$(call targetinfo)
@$(call install_init, foo)
@$(call install_fixup, foo,PACKAGE,foo)
@$(call install_fixup, foo,PRIORITY,optional)
@$(call install_fixup, foo,VERSION,$(FOO_VERSION))
@$(call install_fixup, foo,SECTION,base)
@$(call install_fixup, foo,AUTHOR,”My Name ”)
@$(call install_fixup, foo,DEPENDS,)
@$(call install_fixup, foo,DESCRIPTION,missing)
@$call install_copy, foo, 0, 0, 0755, $(FOO_DIR)/foobar, /dev/null)
@$(call install_finish, foo)
@$(call <strong>to</strong>uch)
The ”header” of this stage defines some information IPKG needs. The important part that we must modify is the
call <strong>to</strong> the install_copy macro (refer <strong>to</strong> section 5.2 for more details about this kind of macros). This call instructs
<strong>PTXdist</strong> <strong>to</strong> include the given file (with PID, UID and permissions) in<strong>to</strong> the IPKG, which means <strong>to</strong> install this file <strong>to</strong>
the target’s root filesystem.
33

4 <strong>PTXdist</strong> Developer’s Manual
From the previous install stage we know this package installs an executable called foo <strong>to</strong> location /usr/bin. We
can do the same for our target by changing the install_copy line <strong>to</strong>:
@$(call install_copy, foo, 0, 0, 0755, $(FOO_DIR)/foo, /usr/bin/foo)
To check it, we just run:
$ ptxdist targetinstall foo
-----------------------------
target: foo.targetinstall
-----------------------------
install_init: preparing for image creation...
install_init: @ARCH@ -> i386 ... done
install_init: preinst not available
install_init: postinst not available
install_init: prerm not available
install_init: postrm not available
install_fixup: @PACKAGE@ -> foo ... done.
install_fixup: @PRIORITY@ -> optional ... done.
install_fixup: @VERSION@ -> 1.1.0 ... done.
install_fixup: @SECTION@ -> base ... done.
install_fixup: @AUTHOR@ -> ”My Name ” ... done.
install_fixup: @DESCRIPTION@ -> missing ... done.
install_copy:
src=/home/jbe/my_new_prj/build-target/foo-1.1.0/foo
dst=/usr/bin/foo
owner=0
group=0
permissions=0755
xpkg_finish: collecting license (unknown) ... done.
xpkg_finish: creating ipkg package ... done.
finished target foo.targetinstall
----------------------------------
target: foo.targetinstall.post
----------------------------------
finished target foo.targetinstall.post
After this command, the target’s root filesystem contains a file called /usr/bin/foo owned by root, its group is
also root and everyone has execution permissions, but only the user root has write permissions.
One last task of this port is still open: A reasonable location for the new menu entry in <strong>PTXdist</strong>’s menu hierarchy.
<strong>PTXdist</strong> arranges its menus on the meaning of each package. Is it a network related <strong>to</strong>ol? Or a scripting language?
Or a graphical application?
Each of these global meanings have their own submenu, where we can add our new entry <strong>to</strong>. We just have <strong>to</strong>
edit the head of our new menu file <strong>to</strong> add it <strong>to</strong> a specific global menu. If our new package is a network related
<strong>to</strong>ol, the head of the menu file should look like:
## SECTION=networking
We can grep through the other menu files from the <strong>PTXdist</strong> main installation rules/ direc<strong>to</strong>ry <strong>to</strong> get an idea what
section names are available:
34

4 <strong>PTXdist</strong> Developer’s Manual
rules/ $ find . -name \*.in | xargs grep ”## SECTION”
./acpid.in:## SECTION=shell_and_console
./alsa-lib.in:## SECTION=system_libraries
./alsa-utils.in:## SECTION=multimedia_sound
./apache2.in:## SECTION=networking
./apache2_mod_python.in:## SECTION=networking
[...]
./klibc-module-init-<strong>to</strong>ols.in:## SECTION=initramfs
./xkeyboard-config.in:## SECTION=multimedia_xorg_data
./xorg-app-xev.in:## SECTION=multimedia_xorg_app
./xorg-app-xrandr.in:## SECTION=multimedia_xorg_app
./host-eggdbus.in:## SECTION=host<strong>to</strong>ols_noprompt
./libssh2.in:## SECTION=networking
Porting a new package <strong>to</strong> <strong>PTXdist</strong> is finished now.
To check it right away, we simply run these two commands:
$ ptxdist clean foo
rm -rf /home/jbe/my_new_prj/state/foo.*
rm -rf /home/jbe/my_new_prj/packages/foo_*
rm -rf /home/jbe/my_new_prj/build-target/foo-1.1.0
$ ptxdist targetinstall foo
[...]
4.2.3 Advanced Rule Files
The previous example on how <strong>to</strong> create a rule file sometimes works as shown above. But most of the time source
archives are not that simple. In this section we want <strong>to</strong> give the user a more detailed selection how the package
will be built.
Adding Static Configure Parameters
The configure scripts of various source archives provide additional parameters <strong>to</strong> enable or disable features, or
<strong>to</strong> configure them in a specific way.
We assume the configure script of our foo example (refer <strong>to</strong> section 4.2.1) supports two additional parameters:
• --enable-debug: Make the program more noisy. It’s disabled by default.
• --with-bar: Also build the special executable bar. Building this executable is also disabled by default.
We now want <strong>to</strong> forward these options <strong>to</strong> the configure script when it runs in the prepare stage. To do so, we
must again open the rule file with our favourite edi<strong>to</strong>r and navigate <strong>to</strong> the prepare stage entry.
<strong>PTXdist</strong> uses the variable FOO_AUTOCONF as the list of parameters <strong>to</strong> be given <strong>to</strong> configure.
Currently this variable is defined <strong>to</strong>:
FOO_AUTOCONF := $(CROSS_AUTOCONF_USR)
The variable CROSS_AUTOCONF_USRis predefined by <strong>PTXdist</strong> and contains all basic parameters <strong>to</strong> instruct configure
<strong>to</strong> prepare for a cross compile environment.
To use the two additional mentioned configure parameters, we supplement this expression as follows:
35

4 <strong>PTXdist</strong> Developer’s Manual
FOO_AUTOCONF := $(CROSS_AUTOCONF_USR) \
--enable-debug \
--with-bar
Note: We recommend <strong>to</strong> use this format with each parameter on a line of its own. That is easier <strong>to</strong> read and a
diff shows more exactly any change.
To do a fast check if this addition was successful, we run:
$ ptxdist print FOO_AUTOCONF
--prefix=/usr --sysconfdir=/etc --host=i586-unknown-linux-gnu --build=i686-host-linux-gnu --enable-debug ¿
--with-bar
Or re-build the package with the new settings:
$ ptxdist drop foo prepare
$ ptxdist targetinstall foo
Adding Dynamic Configure Parameters
Sometimes it makes sense <strong>to</strong> add this kind of parameters on demand only; especially a parameter like
--enable-debug. To let the user decide if this parameter is <strong>to</strong> be used or not, we must add a menu entry. So,
let’s expand our menu. Here is its current content:
## SECTION=project_specific
config FOO
tristate
prompt ”foo”
help
FIXME
We’ll add two menu entries, one for each optional parameter we want <strong>to</strong> add on demand <strong>to</strong> the configure parameters:
## SECTION=project_specific
config FOO
tristate
prompt ”foo”
help
FIXME
if FOO
config FOO_DEBUG
bool
prompt ”add debug noise”
config FOO_BAR
bool
prompt ”build bar”
endif
36

4 <strong>PTXdist</strong> Developer’s Manual
Note: To extend the base name by a suboption name as a trailing component gives <strong>PTXdist</strong> the ability <strong>to</strong> detect
a change in the package’s settings <strong>to</strong> force its rebuild.
To make usage of the new menu entries, we must check them in the rule file and add the correct parameters:
#
# au<strong>to</strong>conf
#
FOO_AUTOCONF := $(CROSS_AUTOCONF_USR)
ifdef PTXCONF_FOO_DEBUG
FOO_AUTOCONF += --enable-debug
else
FOO_AUTOCONF += --disable-debug
endif
ifdef PTXCONF_FOO_BAR
FOO_AUTOCONF += --with-bar
else
FOO_AUTOCONF += --without-bar
endif
It is a good practice <strong>to</strong> add both settings, e.g. --disable-debug even if this is the default case. Sometimes
configure tries <strong>to</strong> guess something and the binary result might differ depending on the build order. For example
some kind of package would also build some X related <strong>to</strong>ols, if X libraries are found. In this case it depends on
the build order, if the X related <strong>to</strong>ols are built or not. All the au<strong>to</strong>check features are problematic here. So, if we
do not want configure <strong>to</strong> guess its settings we must disable everything we do not want
If some parts of a package are built on demand only, they must also be installed on demand only. Besides the
prepare stage, we also must modify our targetinstall stage:
[...]
@$(call install_copy, foo, 0, 0, 0755, $(FOO_DIR)/foo, /usr/bin/foo)
ifdef PTXCONF_FOO_BAR
@$(call install_copy, foo, 0, 0, 0755, $(FOO_DIR)/bar, /usr/bin/bar)
endif
[...]
@$(call install_finish, foo)
@$(call <strong>to</strong>uch)
Now we can play with our new menu entries and check if they are working as expected:
$ ptxdist menuconfig
$ ptxdist targetinstall foo
Whenever we change a FOO related menu entry, <strong>PTXdist</strong> should detect it and re-build the package when a new
build is started.
Managing External Compile Time Dependencies
While running the prepare stage, it could happen that it fails due <strong>to</strong> a missing external dependency.
37

4 <strong>PTXdist</strong> Developer’s Manual
For example:
[...]
checking whether zlib exists....failed
In this example, our new package depends on the compression library zlib. <strong>PTXdist</strong> comes with a target zlib. All
we need <strong>to</strong> do in this case is <strong>to</strong> declare that our new package foo depends on zlib. This kind of dependencies
is managed in the menu file of our new package by simply adding the select ZLIB line. After this addition our
menu file looks like:
## SECTION=project_specific
config FOO
tristate
select ZLIB
prompt ”foo”
help
FIXME
if FOO
config FOO_DEBUG
bool
prompt ”add debug noise”
config FOO_BAR
bool
prompt ”build bar”
endif
<strong>PTXdist</strong> now builds the zlib first and our new package thereafter.
Managing External Compile Time Dependencies on Demand
It is good practice <strong>to</strong> add only those dependecies that are really required for the current configuration of the
package. If the package provides the features foo and bar and its configure provides switches <strong>to</strong> enable/disable
them independently, we can also add dependencies on demand. Let’s assume feature foo needs the compression
library libz and bar needs the XML2 library libxml2. These libraries are only required at runtime if the correspondig
feature is enabled. To add these dependencies on demand, the menu file looks like:
## SECTION=project_specific
config FOO
tristate
select ZLIB if FOO_FOO
select LIBXML2 if FOO_BAR
prompt ”foo”
help
FIXME
if FOO
config FOO_DEBUG
bool
prompt ”add debug noise”
38

4 <strong>PTXdist</strong> Developer’s Manual
config FOO_FOO
bool
prompt ”build foo”
config FOO_BAR
bool
prompt ”build bar”
endif
Note: Do not add these select statements <strong>to</strong> the correspondig menu entry. They must belong <strong>to</strong> the main menu
entry of the package <strong>to</strong> ensure that the calculation of the dependencies between the packages is done in a correct
manner.
Managing External Runtime Dependencies
Some packages are building all of their components and also installing them in<strong>to</strong> the target’s sysroot. But only
their targetinstall stage decides which parts are copied <strong>to</strong> the root filesystem. So, compiling and linking of our
package will work, because everything required is found in the target’s sysroot.
In our example there is a hidden dependency <strong>to</strong> the math library libm. Our new package was built successfully,
because the linker was able <strong>to</strong> link our binaries against the libm from the <strong>to</strong>olchain. But in this case the libm
must also be available in the target’s root filesystem <strong>to</strong> fulfil the runtime dependency: We have <strong>to</strong> force <strong>PTXdist</strong>
<strong>to</strong> install libm. libm is part of the glibc package, but is not installed by default (<strong>to</strong> keep the root filesystem small).
So, it does not help <strong>to</strong> select the GLIBC symbol, <strong>to</strong> get a libm at runtime.
The correct solution here is <strong>to</strong> add a select LIBC_M <strong>to</strong> our menu file. With all the additions above it now looks
like:
## SECTION=project_specific
config FOO
tristate
select ZLIB if FOO_FOO
select LIBXML2 if FOO_BAR
select LIBC_M
prompt ”foo”
help
FIXME
if FOO
config FOO_DEBUG
bool
prompt ”add debug noise”
config FOO_FOO
bool
prompt ”build foo”
config FOO_BAR
bool
prompt ”build bar”
endif
39

4 <strong>PTXdist</strong> Developer’s Manual
Note: There are other packages around, that do not install everything by default. If our new package needs
something special, we must take a look in<strong>to</strong> the menu of the other package how <strong>to</strong> force the required components
<strong>to</strong> be installed and add the corresponding selects <strong>to</strong> our own menu file. In this case it does not help <strong>to</strong> enable
the required parts in our project configuration, because this has no effect on the build order!
Managing Non Au<strong>to</strong><strong>to</strong>ol Packages
Many packages are still coming with a plain Makefile. The user has <strong>to</strong> adapt it <strong>to</strong> make it work in a cross compile
environment as well. <strong>PTXdist</strong> can also handle this kind of packages. We only have <strong>to</strong> specifiy a special prepare
and compile stage.
Such packages often have no special need for any kind of preparation. We can omit this stage by defining this
empty rule:
$(STATEDIR)/foo.prepare:
@$(call targetinfo)
@$(call <strong>to</strong>uch)
To compile the package, we can use make’s feature <strong>to</strong> overwrite variables used in the Makefile. With this feature
we can still use the original Makefile but with our own (cross compile) settings.
Most of the time the generic compile rule can be used, only a few settings are required.
make will be called in this case with:
cd $(FOO_DIR) && $(FOO_MAKE_ENV) $(MAKE) $(FOO_MAKE_OPT)
So, in the rule file only the two variables FOO_MAKE_ENV and FOO_MAKE_OPT must be set, <strong>to</strong> forward the required
settings <strong>to</strong> the package’s buildsystem. If the package cannot be built in parallel, we can also add the
FOO_MAKE_PAR := NO. YES is the default.
Note: FOO is still the name of our example package. It must be replaced by the real package name.
4.2.4 Patching Packages
There can be various reasons why a package must be patched:
• Package is broken for cross compile environments
• Package is broken within a specific feature
• Package is vulnerable and needs some fixes
• or anything else
<strong>PTXdist</strong> handles patching au<strong>to</strong>matically. After extracting the archive, <strong>PTXdist</strong> checks for the existence of a patch
direc<strong>to</strong>ry with the same name as the package. If our package’s name is foo-1.1.0, <strong>PTXdist</strong> searches for patches
in:
1. platform (./configs/arm-qemu-2011.01.0/patches/foo-1.1.0)
2. project (./patches/foo-1.1.0)
3. ptxdist (/path/patches/foo-1.1.0)
The patches from the first location found are used. Note: Due <strong>to</strong> this search order, a <strong>PTXdist</strong> project can replace
global patches from the <strong>PTXdist</strong> installation. This can be useful if a project sticks <strong>to</strong> a specific <strong>PTXdist</strong> revision
but fixes from a more recent revision of <strong>PTXdist</strong> should be used.
40

4 <strong>PTXdist</strong> Developer’s Manual
4.2.5 Creating Patches for a Package
<strong>PTXdist</strong> uses the utilities patch or quilt <strong>to</strong> work with patches or patch series. We recommend quilt, as it can
manage patch series in a very easy way. For this manual we assume quilt is installed on the build host.
Creating a Patch Series for a Package
To create a patch series for the first time, we can run the following steps. We are still using our foo-1.1.0 example
package here:
We create a special direc<strong>to</strong>ry for the patch series in the local project direc<strong>to</strong>ry:
$ mkdir -p patches/foo-1.1.0
<strong>PTXdist</strong> expects a series file in the patch direc<strong>to</strong>ry. Otherwise it fails. Due <strong>to</strong> the fact that we do not have any
patch yet, we’ll start with an empty series file.
$ <strong>to</strong>uch patches/foo-1.1.0/series
Next is <strong>to</strong> extract the package (if already done, we must remove it first):
$ ptxdist extract foo
This will extract the archive and create a symbolic link in the build direc<strong>to</strong>ry pointing <strong>to</strong> our local patch direc<strong>to</strong>ry.
Working this way will ensure that we do not lose our created patches if we enter ptxdist clean fooby accident. In
our case the patches are still present in patches/foo-1.1.0 and can be used the next time we extract the package
again.
All we have <strong>to</strong> do now is <strong>to</strong> do the modification we need <strong>to</strong> make the package work. We change in<strong>to</strong> the build
direc<strong>to</strong>ry and use quilt <strong>to</strong> create new patches, add files <strong>to</strong> respective patches, modify these files and refresh the
patches <strong>to</strong> save our changes.
We recommend this way when modifying source files. But this way is improper when an au<strong>to</strong><strong>to</strong>ols based buildsystem
itself needs modifications. Refer <strong>to</strong> section 4.2.6 on how <strong>PTXdist</strong> can handle this special task.
Adding more Patches <strong>to</strong> a Package
If we want <strong>to</strong> add more patches <strong>to</strong> an already patched package, we can use nearly the same way as creating
patches for the first time. But if the patch series comes from the <strong>PTXdist</strong> main installation, we do not have write
permissions <strong>to</strong> these direc<strong>to</strong>ries (do NEVER work on the main installation direc<strong>to</strong>ries, NEVER, NEVER, NEVER).
Due <strong>to</strong> the search order in which <strong>PTXdist</strong> searches for patches for a specific package, we can copy the global patch
series <strong>to</strong> our local project direc<strong>to</strong>ry. Now we have the permissions <strong>to</strong> add more patches or modify the existing
ones. Also quilt is our friend here <strong>to</strong> manage the patch series.
If we think that our new patches are valuable also for others, or they fix an error, it could be a good idea <strong>to</strong> send
these patches <strong>to</strong> <strong>PTXdist</strong> mainline.
4.2.6 Modifying Au<strong>to</strong><strong>to</strong>olized Packages
Au<strong>to</strong><strong>to</strong>olized packages are very picky when au<strong>to</strong>matically generated files get patched. The patch order is very
important in this case and sometimes it even fails and nowbody knows why.
41

4 <strong>PTXdist</strong> Developer’s Manual
To improve a package’s au<strong>to</strong><strong>to</strong>ols-based build system, <strong>PTXdist</strong> comes with its own project local au<strong>to</strong><strong>to</strong>ols <strong>to</strong>
regenerate the au<strong>to</strong><strong>to</strong>ols template files, instead of patching them. With this feature, only the template files must
be patched, the required configure script and the Makefile.in files are regenerated in the final stages of the
prepare step.
This feature works like the regular patching mechanism. The only difference is the additional au<strong>to</strong>gen.sh file in
the patch direc<strong>to</strong>ry. If it exists and has execution permissions, it will be called after the package was patched
(while the extract stage is running).
Its content depends on developer needs; for the most simple case the content can be:
#!/bin/bash
aclocal $ACLOCAL_FLAGS
lib<strong>to</strong>olize \
--force \
--copy
au<strong>to</strong>reconf \
--force \
--install \
--warnings=cross \
--warnings=syntax \
--warnings=obsolete \
--warnings=unsupported
Note: This way also still not au<strong>to</strong><strong>to</strong>olized package can be au<strong>to</strong><strong>to</strong>olized. We just have <strong>to</strong> add the common au<strong>to</strong><strong>to</strong>ol
template files (configure.ac and Makefile.am for example) via a patch series <strong>to</strong> the package source and the
au<strong>to</strong>gen.sh <strong>to</strong> the patch direc<strong>to</strong>ry.
4.3 Adding binary only Files
Sometimes a few binary files have <strong>to</strong> be added in<strong>to</strong> the root filesystem. Or - <strong>to</strong> be more precise - some files, that
do not need <strong>to</strong> be built in any way.
On the other hand, sometimes files should be included that are not covered by any open source license and so,
should not be shipped in the source code format.
<strong>PTXdist</strong> provides more than one way <strong>to</strong> add such type of data files <strong>to</strong> the root filesystem it creates. The examples
in this chapter refer our generic board support package. It comes with an example how <strong>to</strong> add binary only files
in<strong>to</strong> <strong>PTXdist</strong>’s build mechanism.
4.3.1 Old style - single files
The old style <strong>to</strong> add a simple file is present in <strong>PTXdist</strong> since its early days: Just use the install_copy macro in the
targetinstall stage in your own cus<strong>to</strong>mized rules file.
@$(call install_copy, binary_example, 0, 0, 0644, \
$(PTXDIST_WORKSPACE)/local_src/binary_example/ptx_logo.png, \
/example/ptx_logo.png)
42

4 <strong>PTXdist</strong> Developer’s Manual
The example above is from the file rules/binary_inst.make from Pengutronix’s generic BSP. It copies the file
ptx_logo.png from within the BSP’s direc<strong>to</strong>ry local_src/binary_example <strong>to</strong> target’s root filesystem. Refer 5.2.4
for further information about using the install_copy macro.
The disadvantage of this method is: If we want <strong>to</strong> install more than one file, we need one call <strong>to</strong> the install_copy
macro per file. This is even harder if not only a set of files is <strong>to</strong> be installed, but a whole direc<strong>to</strong>ry tree with files
instead.
4.3.2 New style - using archives
If a whole tree of files is <strong>to</strong> be installed, working with a tar based archive could make life easier. In this case the
archive itself provides all the required information the files are needing <strong>to</strong> be installed in a correct manner:
• the file itself and its name
• the direc<strong>to</strong>ry structure and the final location of every file in this structure
• user and group ID on a per file base
@$(call install_archive, binary_example, -, -, \
$(PTXDIST_WORKSPACE)/local_src/archive_example/pictures.tgz, \
/)
The example shown above is from the file rules/binary_inst.make from Pengutronix’s generic BSP. It extracts
the archive pictures.tgz from within the BSP’s direc<strong>to</strong>ry local_src/archive_example <strong>to</strong> target’s root filesystem.
Refer 5.2.8 for further information about using the install_archive macro.
Using an archive can be usefull <strong>to</strong> install parts of the root filesystem that are not covered by any open source
license. Its possible <strong>to</strong> ship the binaries within the regular BSP, without the need for their sources. <strong>How</strong>ever it is
possible for the cus<strong>to</strong>mer <strong>to</strong> re-create everything required from the BSP <strong>to</strong> get their target up and running again.
Another use case for the archive method could be the support for different development teams. One team provides
a software component in the archive format, the other team does not neet <strong>to</strong> build it but can use it in the
same way than every other software component.
4.3.3 Creating a Rules File
To get a rules and menu file we can copy the one from the generic BSP, or we let <strong>PTXdist</strong> create them for us.
$ ptxdist newpackage file
ptxdist: creating a new ’file’ package:
ptxdist: enter package name.......: my_binfiles
ptxdist: enter version number.....: 1
ptxdist: enter package author.....: Juergen Beisert
ptxdist: enter package section....: rootfs
Now two new files are present in the BSP:
1. rules/my_binfiles.in The template for the menu
2. rules/my_binfiles.make The rules template
43

4 <strong>PTXdist</strong> Developer’s Manual
Both files now must be cus<strong>to</strong>mized <strong>to</strong> meet our requirements. Due <strong>to</strong> the answer rootfs <strong>to</strong> the ”enter package
section” question, we will find the new menu entry in:
Root Filesystem --->
< > my_binfiles (NEW)
Enabling this new entry will also run our stages in rules/my_binfiles.make the next time we enter:
$ ptxdist go
44

5 <strong>PTXdist</strong> Reference
5.1 Variables Reference
The following variables are provided by <strong>PTXdist</strong> <strong>to</strong> simplify creating rule files. Every developer should use these
variables in every single line in the rule file <strong>to</strong> avoid any further adaption when external paths are changed.
To get their content related <strong>to</strong> the current project, we can simply run a:
$ ptxdist print PTXDIST_TOPDIR
/usr/local/lib/ptxdist-2011.01.0
Replace the PTXDIST_TOPDIR with one of the other generic variables <strong>PTXdist</strong> provides.
5.1.1 PTXDIST_TOPDIR
Points always <strong>to</strong> the installation direc<strong>to</strong>ry of <strong>PTXdist</strong>.
5.1.2 PTXDIST_WORKSPACE
Everything that references PTXDIST_WORKSPACE will use the active projects’s folder.
5.1.3 PTXDIST_SYSROOT_CROSS
PTXDIST_SYSROOT_CROSS points <strong>to</strong> a direc<strong>to</strong>ry tree all cross relevant executables, libraries and header files are
installed <strong>to</strong> in the current project. All of the project’s packages built for the host <strong>to</strong> create data for the target
are searching in this direc<strong>to</strong>ry tree for their dependencies (executables, header and library files). Use
$(PTXDIST_SYSROOT_CROSS)/bin <strong>to</strong> install executables, $(PTXDIST_SYSROOT_CROSS)/include for header files and
$(PTXDIST_SYSROOT_CROSS)/lib for libraries.
5.1.4 PTXDIST_SYSROOT_HOST
PTXDIST_SYSROOT_HOST points <strong>to</strong> a direc<strong>to</strong>ry tree all host relevant executables, libraries and header files are
installed <strong>to</strong>. All project’s packages built for the host are searching in this direc<strong>to</strong>ry tree for their dependencies
(executables, header and library files). Use $(PTXDIST_SYSROOT_HOST)/bin <strong>to</strong> install executables,
$(PTXDIST_SYSROOT_HOST)/include for header files and $(PTXDIST_SYSROOT_HOST)/lib for libraries.
45

5 <strong>PTXdist</strong> Reference
5.1.5 PTXDIST_SYSROOT_TARGET
PTXDIST_SYSROOT_TARGET points <strong>to</strong> a direc<strong>to</strong>ry tree all target relevant libraries and header files are installed <strong>to</strong>.
All project’s packages built for the target are searching in this direc<strong>to</strong>ry tree for their dependencies (header and
library files). These files are for compile time only (for example <strong>to</strong> link a target executable against a target library),
not for runtime! Use $(PTXDIST_SYSROOT_TARGET)/include for header files and $(PTXDIST_SYSROOT_TARGET)/lib
for libraries.
Other useful variables:
5.1.6 CROSS_PATH
Use <strong>to</strong> find cross <strong>to</strong>ols. This path must be used <strong>to</strong> create anything that depends on the target’s architecture, but
needs something running on the host <strong>to</strong> do the job. Examples:
Creating a jffs2 image from the target’s root filesystem This will need a <strong>to</strong>ol running on the host, but it will
create data or code that runs on or is used on the target
Building a library for the target If this library needs other resources <strong>to</strong> be built (other libraries) its configure
finds the right information in this path.
5.1.7 HOST_PATH
Used <strong>to</strong> find host <strong>to</strong>ols. This path must be used <strong>to</strong> create anything that not depends on the architecture.
5.1.8 ROOTDIR
ROOTDIR points <strong>to</strong> the root of the target’s root filesystem in the current project. Used in very rare cases (<strong>to</strong> create
strange packages based on data in target’s root filesystem for example).
5.1.9 PTXCONF_PLATFORM
PTXCONF_PLATFORMexpands <strong>to</strong> the name of the currently selected platform. This name is used in various file names
and paths.
5.1.10 PTXDIST_PLATFORMSUFFIX
PTXDIST_PLATFORMSUFFIX expands <strong>to</strong> the name of the currently selected platform, but with a leading dot. This is
used in various files <strong>PTXdist</strong> should search for.
5.1.11 PTXDIST_PLATFORMCONFIGDIR
PTXDIST_PLATFORMCONFIGDIR points <strong>to</strong> the direc<strong>to</strong>ry tree of the currently selected platform. This path is used in
various search functions.
5.1.12 PTXDIST_PLATFORMDIR
PTXDIST_PLATFORMDIR points <strong>to</strong> the direc<strong>to</strong>ry build tree of the currently selected platform.
46

5 <strong>PTXdist</strong> Reference
5.2 Rule File Macro Reference
Rules files in <strong>PTXdist</strong> are using macros <strong>to</strong> get things work. Its highly recommended <strong>to</strong> use these macros instead
<strong>to</strong> do something by ourself. Using the macros is portable and such easier <strong>to</strong> maintain in the case a project should
be upgraded <strong>to</strong> a more recent <strong>PTXdist</strong> version.
This chapter describes the predefined macros in <strong>PTXdist</strong> and their usage.
Note: This list is not complete yet.
5.2.1 targetinfo
Usage:
$(call targetinfo)
Gives a feedback, what build stage is just started. Thats why it should always be the first call for each stage. For
the package foo and the compile stage it will output:
--------------------
target: foo.compile
--------------------
5.2.2 <strong>to</strong>uch
Usage:
$(call <strong>to</strong>uch)
Gives a feedback, what build stage is just finished. Thats why it should always be the last call for each stage. For
the package foo and the compile stage it will output:
finished target foo.compile
5.2.3 clean
Usage:
$(call clean, )
Removes the given direc<strong>to</strong>ry .
5.2.4 install_copy
Usage:
$(call install_copy, , , , , [, ])
Installs given file or direc<strong>to</strong>ry in<strong>to</strong>:
47

5 <strong>PTXdist</strong> Reference
• the project’s platform-versatilepb/root/
• the project’s platform-versatilepb/root-debug/
• an ipkg packet in the project’s platform-versatilepb/packages/
Some of the parameters have fixed meanings:
Name of the IPKG the macro should work on
User ID (in a numerical value) the file should use in the target’s root filesystem
Group ID (in a numerical value) the file should use in the target’s root filesystem
Permission (in an octal value) the file should use in the target’s root filesystem
The remaining parameters vary with the use case:
The parameter can be:
• a direc<strong>to</strong>ry path that should be created in the target’s root filesystem. In this case the must
be omitted. The given path must always start with a / and means the root of the target’s filesystem.
• an absolute path <strong>to</strong> a file that should be copied <strong>to</strong> the target’s root filesystem. To avoid fixed paths, all
packages are providing the _DIR variable. So, this parameter in our foo example package can
be a $(FOO_DIR)/foo.
• a minus sign (-). <strong>PTXdist</strong> uses the parameter in this case <strong>to</strong> locate the file <strong>to</strong> copy from.
This only works if the package uses the default install stage. Only in this case an additional folder in
platform-versatilepb/packages will be created for the package and its files. For our foo example package
this direc<strong>to</strong>ry is platform-versatilepb/packages/foo-1.1.0.
The parameter can be:
• omitted if a direc<strong>to</strong>ry in target’s root filesystem should be created. For this case the direc<strong>to</strong>ry <strong>to</strong> be created
is in the parameter.
• an absolute path and filename with its root in target’s root filesysem. It must start with a slash (/). If also
the parameter was given, the file can be renamed while copying.
If the parameter was given as a minus sign (-) the is also used <strong>to</strong> locate the
source. For our foo example package if we give as /usr/bin/foo, <strong>PTXdist</strong> copies the file
platform-versatilepb/packages/foo-1.1.0/usr/bin/foo
Due <strong>to</strong> the complexity of this macro, here are some usage examples:
Create a direc<strong>to</strong>ry in the root filesystem:
$(call install_copy, foo, 0, 0, 0755, /home/user-foo)
Copy a file from the package build direc<strong>to</strong>ry <strong>to</strong> the root filesystem:
$(call install_copy, foo, 0, 0, 0755, $(FOO_DIR)/foo, /usr/bin/foo)
Copy a file from the package build direc<strong>to</strong>ry <strong>to</strong> the root filesystem and rename it:
$(call install_copy, foo, 0, 0, 0755, $(FOO_DIR)/foo, /usr/bin/bar)
Copy a file from the package install direc<strong>to</strong>ry <strong>to</strong> the root filesystem:
$(call install_copy, foo, 0, 0, 0755, -, /usr/bin/foo)
48

5 <strong>PTXdist</strong> Reference
5.2.5 install_tree
Usage:
$(call install_tree, , , , , )
Installs the whole direc<strong>to</strong>ry tree with all files from the given direc<strong>to</strong>ry in<strong>to</strong>:
• the project’s platform-versatilepb/root/
• the project’s platform-versatilepb/root-debug/
• an ipkg packet in the project’s platform-versatilepb/packages/
Some of the parameters have fixed meanings:
Name of the IPKG, the macro should work on
User ID (in a numerical value) the direc<strong>to</strong>ries and files should use in target’s root filesystem
Group ID (in a numerical value) the direc<strong>to</strong>ries and files should use in target’s root filesystem
This is the path <strong>to</strong> the tree of direc<strong>to</strong>ries and files <strong>to</strong> be installed
The basename of the <strong>to</strong> be installed tree in the root filesystem
Note: This installation macro
• uses the same permission flags in the destination dir as found in the source dir. This is valid for direc<strong>to</strong>ries
and regular files
• skips all direc<strong>to</strong>ries with names like .svn, .git, .pc and CVS in the source direc<strong>to</strong>ry
Examples:
Install the whole tree found in /home/jbe/foo <strong>to</strong> the root filesystem at location /usr/share/bar.
$(call install_tree, foo, 0, 0, /home/jbe/foo, /usr/share/bar)
5.2.6 install_alternative
Usage:
$(call install_alternative, , , , , )
Installs given files or direc<strong>to</strong>ries in<strong>to</strong>:
• the project’s platform-versatilepb/root/
• the project’s platform-versatilepb/root-debug/
• an ipkg packet in the project’s platform-versatilepb/packages/
The base parameters and their meanings:
Name of the IPKG, the macro should work on
User ID (in a numerical value) the file should use in target’s root filesystem
Group ID (in a numerical value) the file should use in target’s root filesystem
Permission (in an octal value) the file should use in target’s root filesystem
49

5 <strong>PTXdist</strong> Reference
The parameter is meant as an absolute path and filename in target’s root filesystem. <strong>PTXdist</strong>
searches for the source of this file in:
• the local project
• in the used platform
• <strong>PTXdist</strong>’s install path
• in the current package
As this search algorithm is complex, here an example for the file /etc/foo in package FOO. <strong>PTXdist</strong> will search for
this file in the following order:
• project’s direc<strong>to</strong>ry projectroot.versatilepb/etc/foo
• project’s direc<strong>to</strong>ry projectroot/etc/foo.versatilepb
• project’s direc<strong>to</strong>ry configs/arm-qemu-2011.01.0/projectroot/etc/foo
• project’s direc<strong>to</strong>ry projectroot/etc/foo
• ptxdist’s direc<strong>to</strong>ry generic/etc/foo
• project’s direc<strong>to</strong>ry $(FOO_DIR)/etc/foo
The generic rules are looking like the following:
• $(PTXDIST_WORKSPACE)/projectroot$(PTXDIST_PLATFORMSUFFIX)/etc/foo
• $(PTXDIST_WORKSPACE)/projectroot/etc/foo$(PTXDIST_PLATFORMSUFFIX)
• $(PTXDIST_PLATFORMCONFIGDIR)/projectroot/etc/foo
• $(PTXDIST_WORKSPACE)/projectroot/etc/foo
• $(PTXDIST_TOPDIR)/generic/etc/foo
• $(FOO_DIR)/etc/foo
Note: You can get the current values for the listed variables above via running <strong>PTXdist</strong> with the print parameter:
ptxdist print PTXDIST_PLATFORMSUFFIX
5.2.7 install_link
Usage:
$(call install_link, , , )
Installs a symbolic link in<strong>to</strong>:
• the project’s platform-versatilepb/root/
• the project’s platform-versatilepb/root-debug/
• an ipkg packet in the project’s platform-versatilepb/packages/
The parameters and their meanings:
Name of the IPKG, the macro should work on
Path and name the link should point <strong>to</strong>. Note: This macro rejects absolute paths. If needed use
relative paths instead.
50

5 <strong>PTXdist</strong> Reference
Path and name of the symbolic link.
A few usage examples.
Create a symbolic link as /usr/lib/libfoo.so pointing <strong>to</strong> libfoo.so.1.1.0 in the same direc<strong>to</strong>ry:
$(call install_link, foo, libfoo.so.1.1.0, /usr/lib/libfoo.so)
Create a symbolic link as /usr/bin/foo pointing <strong>to</strong> /bin/bar:
$(call install_link, foo, ../../bin/bar, /usr/bin/foo)
5.2.8 install_archive
Usage:
$(call install_archive, , , , , )
Installs archives content in<strong>to</strong>:
• the project’s platform-versatilepb/root/
• the project’s platform-versatilepb/root-debug/
• an ipkg packet in the project’s platform-versatilepb/packages/
All parameters have fixed meanings:
Name of the IPKG, the macro should work on
User ID (in a numerical value) all files and direc<strong>to</strong>ry of the archive should use in target’s root filesystem.
A ’-’ uses file’s/direc<strong>to</strong>rie’s UID in the archive
Group ID (in a numerical value) the files and direc<strong>to</strong>ries should use in target’s root filesystem. A ’-’ uses
file’s/direc<strong>to</strong>rie’s GID in the archive
Name of the archive <strong>to</strong> be used in this call. The given path and filename is used as is
Base path component in the root filesystem the archive should be extracted <strong>to</strong>. Can be just ’/’ for
root.
5.3 Rule file layout
Each rule file provides <strong>PTXdist</strong> with the required steps <strong>to</strong> be done on a per package base:
• get
• extract
• prepare
• compile
• install
• targetinstall
51

5 <strong>PTXdist</strong> Reference
5.3.1 Default stage rules
As for most packages these steps can be done in a default way, <strong>PTXdist</strong> provides generic rules for each package.
If a package’s rule file does not provide a specific stage rule, the default stage rule will be used instead.
Omitting one of the stage rules does not mean that <strong>PTXdist</strong> skips this stage!
In this case the default stage rule is used instead.
get Stage Default Rule
If the get stage is omitted, <strong>PTXdist</strong> runs instead:
$(STATEDIR)/@package@.get:
@$(call targetinfo)
@$(call <strong>to</strong>uch)
Which means this step is skipped.
If the package is an archive that must be downloaded from the web, the following rule must exist in this case:
$(@package@_SOURCE):
@$(call targetinfo)
@$(call get, @package@)
extract Stage Default Rule
If the extract stage is omitted, <strong>PTXdist</strong> runs instead:
$(STATEDIR)/@package@.extract:
@$(call targetinfo)
@$(call clean, $(@package@_DIR))
@$(call extract, @package@)
@$(call patchin, @package@)
@$(call <strong>to</strong>uch)
prepare Stage Default Rule
If the prepare stage is omitted, <strong>PTXdist</strong> runs a default stage rule depending on some variable settings.
If the package’s rule file defines a @package@_AUTOCONF variable (FOO_AUTOCONF for our foo example), <strong>PTXdist</strong> treats
this package as an au<strong>to</strong><strong>to</strong>olized package and runs:
$(STATEDIR)/@package@.prepare:
@$(call targetinfo)
@$(call clean, $(@package@_DIR)/config.cache)
cd $(@package@_DIR)/$(@package@_SUBDIR) && \
$(@package@_PATH) $(@package@_ENV) \
./configure $(@package@_AUTOCONF)
@$(call <strong>to</strong>uch)
52

5 <strong>PTXdist</strong> Reference
If the package’s rule file defines a @package@_CMAKE variable (FOO_CMAKE for our foo example), <strong>PTXdist</strong> treats this
package as a cmake based package and runs:
$(STATEDIR)/@package@.prepare:
@$(call targetinfo)
@$(call clean, $(@package@_DIR)/config.cache)
cd $(@package@_DIR) && \
$(@package@_PATH) $(@package@_ENV) \
cmake $(@package@_CMAKE)
@$(call <strong>to</strong>uch)
compile Stage Default Rule
If the compile stage is omitted, <strong>PTXdist</strong> runs instead:
$(STATEDIR)/@package@.compile:
@$(call targetinfo)
cd $(@package@_DIR) && \
$(@package@_PATH) $(@package@_MAKE_ENV) \
$(MAKE) $(@package@_MAKE_OPT) $(@package@_MAKE_PAR)
@$(call <strong>to</strong>uch)
Note: @package@_MAKE_PAR can be defined <strong>to</strong> YES or NO <strong>to</strong> control if the package can be built in parallel.
install Stage Default Rule
If the install stage is omitted, <strong>PTXdist</strong> runs instead:
$(STATEDIR)/@package@.install:
@$(call targetinfo)
cd $(@package@_DIR) && \
$(@package@_PATH) $(@package@_MAKE_ENV) \
$(MAKE) $(@package@_INSTALL_OPT)
@$(call <strong>to</strong>uch)
Note: @package@_INSTALL_OPT is always defined <strong>to</strong> install if not otherwise specified. This value can be replaced
by a package’s rule file definition.
targetinstall Stage Default Rule
There is no default rule for a package’s targetinstall state. <strong>PTXdist</strong> has no idea what is required on the target at
runtime. This stage is up <strong>to</strong> the developer only. Refer <strong>to</strong> section 5.2 for further info on how <strong>to</strong> select files <strong>to</strong> be
included in the target’s root filesystem.
5.3.2 Skipping a Stage
For the case that a specific stage should be skipped, an empty rule must be provided:
$(STATEDIR)/@package@.:
@$(call targetinfo)
@$(call <strong>to</strong>uch)
Replace the by get, extract, prepare, compile, install or targetinstall.
53

5 <strong>PTXdist</strong> Reference
5.4 <strong>PTXdist</strong> parameter reference
<strong>PTXdist</strong> is a command line <strong>to</strong>ol, which is basicly called as:
$ ptxdist [options]
5.4.1 Setup and Project Actions
menu: This will start a menu frontend <strong>to</strong> control some of <strong>PTXdist</strong>’s features in a menu based convenient way. This
menu handles the actions menuconfig, platformconfig, kernel config, select, platform, boardsetup, setup, go and
images.
select : This action will select a userland configuration. This step is only required in projects, where
no selected_ptxconfig file is present. The argument must point <strong>to</strong> a valid userland configuration file.
<strong>PTXdist</strong> provides this feature <strong>to</strong> enable the user <strong>to</strong> maintain more than one userland configuration in the same
project.
platform : This action will select a platform configuration. This step is only required in projects, where
no selected_platform file is present. The argument must point <strong>to</strong> a valid platform configuration file.
<strong>PTXdist</strong> provides this feature <strong>to</strong> enable the user <strong>to</strong> maintain more than one platform in one project.
setup: <strong>PTXdist</strong> uses some global settings, independent from the project it is working on. These settings belong
<strong>to</strong> users preferences or simply some network settings <strong>to</strong> permit <strong>PTXdist</strong> <strong>to</strong> download required packages.
boardsetup: <strong>PTXdist</strong> based projects can provide information <strong>to</strong> setup and configure the target au<strong>to</strong>matically. This
action let the user setup the environment specific settings like the network IP address and so on.
projects: If the generic projects coming in a separate archive are installed, this actions lists the projects a user
can clone for its own work.
clone : This action clones an existing project from the projects list in<strong>to</strong> a new direc<strong>to</strong>ry. The
argument must be a name gotten from ptxdist projects command, the argument is the new project
(and direc<strong>to</strong>ry) name, creeated in the current direc<strong>to</strong>ry.
menuconfig: Start the menu <strong>to</strong> configure the project’s root filesystem. This is in respect <strong>to</strong> userland only. Its the
main menu <strong>to</strong> select applications and libraries, the root filesystem of the target should consist of.
menuconfig platform: This action starts the menu <strong>to</strong> configure platform’s settings. As these are architecture and
target specific settings it configures the <strong>to</strong>olchain, the kernel and a bootloader (but no userland components).
Due <strong>to</strong> a project can support more than one platform, this will configure the currently selected platform. The
shortform for this action is platformconfig.
menuconfig kernel: Start the menu <strong>to</strong> configure the platform’s kernel. As a project can support more than one
platform, this will configure the currently selected platform. The shortform for this action is kernelconfig.
menuconfig u-boot-v2 | barebox: This action starts the configure menu for the selected bootloader. It depends
on the platform settings which bootloader is enabled and <strong>to</strong> be used as an argument <strong>to</strong> the menuconfig action parameter.
Due <strong>to</strong> a project can support more than one platform, this will configure the bootloader of the currently
selected platform. The shortform for this action is platformconfig.
5.4.2 Build Actions
go: This action will build all enabled packages in the current project configurations (platform and userland). It
will also rebuild reconfigured packages if any or build additional packages if they where enabled meanwhile. If
enables this step also builds the kernel and bootloader image.
54

5 <strong>PTXdist</strong> Reference
images: Most of the time this is the last step <strong>to</strong> get the required files and/or images for the target. It creates
filesystems or device images <strong>to</strong> be used in conjunction with the target’s filesystem media. The result can be
found in the images/ direc<strong>to</strong>ry of the project or the platform direc<strong>to</strong>ry.
5.4.3 Clean Actions
clean: The cleanaction will remove all generated files while the last gorun: All build, packages and root filesystem
direc<strong>to</strong>ries. Only the selected configuration files are left un<strong>to</strong>uched. This is a way <strong>to</strong> start a fresh build cycle.
clean root: This action will only clean the root filesystem direc<strong>to</strong>ries. All the build direc<strong>to</strong>ries are left un<strong>to</strong>uched.
Using this action will regenerate all ipkg packets from the already built packages and also the root filesystem
direc<strong>to</strong>ries in the next go action. The clean root and go action is usefull, if the targetinstall stage for all packages
should run again.
distclean: The distcleanaction will remove all files that are not part of the main project. It removes all generated
files and direc<strong>to</strong>ries like the clean action and also the created links in any platform and/or select action.
55

6 Various Aspects of Daily Work
6.1 Using an External Kernel Source Tree
This application note describes how <strong>to</strong> use an external kernel source tree within a <strong>PTXdist</strong> project. In this case
the external kernel source tree is managed by GIT.
6.1.1 Cloning the Linux Kernel Source Tree
In this example we are using the officiall Linux kernel developmen tree.
jbe@oc<strong>to</strong>pus:~$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/<strong>to</strong>rvalds/linux-2.6
[...]
jbe@oc<strong>to</strong>pus:~$ ls -l
[...]
drwxr-xr-x 38 jbe ptx 4096 2009-03-17 10:21 myprj
drwxr-xr-x 25 jbe ptx 4096 2009-03-17 10:42 linux-2.6
[...]
6.1.2 Configuring <strong>PTXdist</strong>
To make <strong>PTXdist</strong> use of this kernel source tree, we run
jbe@oc<strong>to</strong>pus:~$ ptxdist setup
and navigate <strong>to</strong> Source Direc<strong>to</strong>ries, Prefix for kernel trees and enter the base path <strong>to</strong> the kernel source tree in<strong>to</strong>
this menu entry (omit the kernel source tree direc<strong>to</strong>ry name itself). The kernel source tree direc<strong>to</strong>ry <strong>to</strong> be used in
this base path will be setup on a per project base. So it will be possible <strong>to</strong> place more than one kernel source tree
in the base path.
6.1.3 Configuring the <strong>PTXdist</strong> Project
Now we can setup this kernel source tree <strong>to</strong> be used in our project. <strong>PTXdist</strong> will handle it in the same way as a
kernel part of the project. Due <strong>to</strong> this, we must setup:
• Some kind of kernel version
• Kernel configuration
• Image type used on our target architecture
• If we want <strong>to</strong> build modules
• Patches <strong>to</strong> be used (or not)
56

6 Various Aspects of Daily Work
Let’s setup these <strong>to</strong>pics. Assumption is here, the direc<strong>to</strong>ry /myprj contains a valid <strong>PTXdist</strong> project. We just add
the kernel component <strong>to</strong> it.
jbe@oc<strong>to</strong>pus:~$ cd myprj
jbe@oc<strong>to</strong>pus:~/myprj$ ptxdist platformconfig
We must enable the Linux kernel entry first, <strong>to</strong> enable kernel building as part of the project. After enabling this
entry, we must enter this entry, and:
• Setting up the kernel version with the name of kernel source tree direc<strong>to</strong>ry. In our case shown above it
would be linux-2.6.
• Selecting the correct image type in the entry Image Type.
• Configuring the kernel within the menu entry patching & configuration.
– If no patches should be used on <strong>to</strong>p of the selected kernel source tree, we keep the patch series file
entry empty. As GIT should help us <strong>to</strong> create these patches for deployment, it should be kept empty
on default in this first step.
– Select a name for the kernel configuration file and enter it in<strong>to</strong> the kernel config file entry.
• As we want <strong>to</strong> use an existing kernel source tree we also must enable the Local kernel tree menu entry.
Now we can leave the menu and s<strong>to</strong>re the new setup. The only still missing component is a valid kernel config
file now. We can use one of the default config files the Linux kernel supports as a starting point. To do so, we
copy one <strong>to</strong> the location, where <strong>PTXdist</strong> expects it in the current project. In a multi platform project this location
is the platform direc<strong>to</strong>ry usally in configs/. We must s<strong>to</strong>re the file with a name selected in
the platform setup menu (kernel config file).
6.1.4 Work Flow
Now its up <strong>to</strong> ourself working on the GIT based kernel source tree and using <strong>PTXdist</strong> <strong>to</strong> include the kernel in<strong>to</strong>
the root filesystem.
To configure the kernel source tree, we simply run:
jbe@oc<strong>to</strong>pus:~/myprj$ ptxdist kernelconfig
To build the kernel:
jbe@oc<strong>to</strong>pus:~/myprj$ ptxdist targetinstall kernel
To rebuild the kernel:
jbe@oc<strong>to</strong>pus:~/myprj$ ptxdist drop kernel targetinstall
jbe@oc<strong>to</strong>pus:~/myprj$ ptxdist targetinstall kernel
6.2 Discovering Runtime Dependencies
Often it happens that an application on the target fails <strong>to</strong> run, because one of its dependencies is not fulfilled.
This section should give some hints on how <strong>to</strong> discover these dependencies.
57

6 Various Aspects of Daily Work
6.2.1 Dependencies on Shared Libraries
Getting the missed shared library for example at runtime is something easily done: The dynamic linker prints the
missing library <strong>to</strong> the console.
To check at build time if all other dependencies are present is easy, <strong>to</strong>o. The architecture specific readelf <strong>to</strong>ol
can help us here. It comes with the OSELAS.Toolchain and is called via arm-v4t-linux-gnueabi-readelf (this
example uses the one coming with the arm-v4t-linux-gnueabi <strong>to</strong>olchain).
To test the foo binary from our new package FOO, we simply run:
$ arm-v4t-linux-gnueabi-readelf -d platform-versatilepb/root/usr/bin/foo | grep NEEDED
0x00000001 (NEEDED)
Shared library: [libm.so.6]
0x00000001 (NEEDED)
Shared library: [libz.so.1]
0x00000001 (NEEDED)
Shared library: [libc.so.6]
We now can check if all of the listed libraries are present in the root filesystem. This works for shared libraries,
<strong>to</strong>o. It is also a way <strong>to</strong> check if various configurations of our package are working as expected (e.g. disabling a
feature should also remove the required dependency of this feature).
6.2.2 Dependencies on other Resources
Sometimes a binary fails <strong>to</strong> run due <strong>to</strong> missing files, direc<strong>to</strong>ries or device nodes. Often the error message (if any)
that the binary creates in this case is ambiguous. Here the strace <strong>to</strong>ol can help us, namely <strong>to</strong> observe the binary
at runtime. strace shows all the system calls that the binary or its shared libraries are performing.
strace is one of the target debugging <strong>to</strong>ols which <strong>PTXdist</strong> provides in its Debug Tools menu.
After adding strace <strong>to</strong> the root filesystem, we can use it and observe our foo binary:
$ strace usr/bin/foo
execve(”/usr/bin/foo”, [”/usr/bin/foo”], [/* 41 vars */]) = 0
brk(0)
= 0x8e4b000
access(”/etc/ld.so.preload”, R_OK) = -1 ENOENT (No such file or direc<strong>to</strong>ry)
open(”/etc/ld.so.cache”, O_RDONLY) = 3
fstat64(3, {st_mode=S_IFREG|0644, st_size=77488, ...}) = 0
mmap2(NULL, 77488, PROT_READ, MAP_PRIVATE, 3, 0) = 0xb7f87000
close(3) = 0
open(”/lib//lib/libm-2.5.1.so”, O_RDONLY) = 3
read(3, ”\177ELF\1\1\1\0\0\0\0\0\0\0\0\0\3\0\3\0\1\0\0\0p%\0\000”..., 512) = 512
mmap2(NULL, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0xb7f86000
fstat64(3, {st_mode=S_IFREG|0555, st_size=48272, ...}) = 0
mmap2(NULL, 124824, PROT_READ|PROT_EXEC, MAP_PRIVATE|MAP_DENYWRITE, 3, 0) = 0xb7f67000
mmap2(0xb7f72000, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_FIXED|MAP_DENYWRITE, 3, 0xb) = 0xb7f72000
mmap2(0xb7f73000, 75672, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_FIXED|MAP_ANONYMOUS, -1, 0) = 0xb7f73000
close(3) = 0
open(”/lib/libc.so.6”, O_RDONLY) = 3
read(3, ”\177ELF\1\1\1\0\0\0\0\0\0\0\0\0\3\0\3\0\1\0\0\0\332X\1”..., 512) = 512
fstat64(3, {st_mode=S_IFREG|0755, st_size=1405859, ...}) = 0
[...]
Occasionally the output of strace can be very long and the interesting parts are lost. So, if we assume the binary
tries <strong>to</strong> open a nonexisting file, we can limit the output <strong>to</strong> all open system calls:
58

6 Various Aspects of Daily Work
$ strace -e open usr/bin/foo
open(”/etc/ld.so.cache”, O_RDONLY) = 3
open(”/lib/libm-2.5.1.so”, O_RDONLY) = 3
open(”/lib/libz.so.1.2.3”, O_RDONLY) = 3
open(”/lib/libc.so.6”, O_RDONLY) = 3
[...]
open(”/etc/foo.conf”, O_RDONLY) = -1 ENOENT (No such file or direc<strong>to</strong>ry)
The binary may fail due <strong>to</strong> a missing /etc/foo.conf. This could be a hint on what is going wrong (it might not be
the final solution).
6.3 Debugging with CPU emulation
If we do not need some target related feature <strong>to</strong> run our application, we can also debug it through a simple CPU
emulation. Thanks <strong>to</strong> QEMU we can run ELF binaries for other architectures than our build host is.
6.3.1 Running an Application made for a different Architecture
<strong>PTXdist</strong> creates a fully working root filesystem with all runtime components in platform-versatilepb/root/. Lets
assume we made a <strong>PTXdist</strong> based project for a arm926 CPU. Part of this project is our application myapp we are
currently working on. <strong>PTXdist</strong> builds the root filesystem and also compiles our application. It also installs it <strong>to</strong>
usr/bin/myapp in the root filesystem.
With this preparation we can run it on our build host:
$ cd platform-versatilepb/root
platform-versatilepb/root $ qemu-arm -cpu arm926 -L . usr/bin/myapp
This command will run the application usr/bin/myapp built for an arm926 CPU on the build host and is using all
library compontents from the current direc<strong>to</strong>ry.
For the stdin and -out QEMU uses the regular mechanism of the build host’s operating system. Using QEMU in
this way let us simply check our programs. There are also QEMU environments for other architectures available.
6.3.2 Debugging an Application made for a different Architecture
Debugging our application is also possible with QEMU. All we need are a root filesystem with debug symbols
available, QEMU and an architecture aware debugger.
The root filesystem with debug symbols will be provided by <strong>PTXdist</strong>, the architecture aware debugger comes with
the OSELAS.Toolchain. Two consoles are required for this debug session in this example. We start the QEMU in
the first console as:
$ cd platform-versatilepb/root-debug
platform-versatilepb/root-debug $ qemu-arm -g 1234 -cpu arm926 -L . usr/bin/myapp
Note: <strong>PTXdist</strong> always builds two root filesystems. platform-versatilepb/root/and platform-versatilepb/root-debug/.
platform-versatilepb/root/ contains all components without debug information (all binaries are in the same
size as used later on on the real target), while all components in platform-versatilepb/root-debug/ still
containing the debug symbols and are much bigger in size.
59

6 Various Aspects of Daily Work
The added -g 1234 parameter lets QEMU wait for a GDB connection <strong>to</strong> run the application.
In the second console we start GDB with the correct architecture support. This GDB comes with the same OS-
ELAS.Toolchain that was also used <strong>to</strong> build the project. In our example we are using the arm-v4t-linux-gnueabi
<strong>to</strong>olchain for our qemu-arm CPU:
$ arm-v4t-linux-gnueabi-gdbtui root-debug/usr/bin/myapp
This will run a curses based GDB. Not so easy <strong>to</strong> handle (we must enter all the commands and cannot click with
a mouse!), but very fast <strong>to</strong> take a quick look at our application.
At first we tell GDB where <strong>to</strong> look for debug symbols. The correct direc<strong>to</strong>ry here is platform-versatilepb/root-debug/.
(gdb) set solib-absolute-prefix platform-versatilepb/root-debug
Next we connect this GDB <strong>to</strong> the waiting QEMU:
(gdb) target remote localhost:1234
Remote debugging using localhost:1234
[New Thread 1]
0x40096a7c in _start () from root-debug/lib/ld.so.1
As our application is already started, we can’t use the GDB command start <strong>to</strong> run it until it reaches main(). We
set a breakpoint instead at main() and continue the application:
(gdb) break main
Breakpoint 1 at 0x100024e8: file myapp.c, line 644.
(gdb) continue
Continuing.
Breakpoint 1, main (argc=1, argv=0x4007f03c) at myapp.c:644
The <strong>to</strong>p part of the running gdbtui console will always show us the current source line. Due <strong>to</strong> the root-debug/
direc<strong>to</strong>ry usage all debug information for GDB is available.
Now we can step through our application by using the commands step, next, stepi, nexti, until and so on.
Note: It might be impossible for GDB <strong>to</strong> find debug symbols for components like the main C runtime library. In
this case they where stripped while building the <strong>to</strong>olchain. There is a switch in the OSELAS.Toolchain menu <strong>to</strong>
keep the debug symbols also for the C runtime library. But be warned: This will enlarge the OSELAS.Toolchain
installation on your harddisk! When the <strong>to</strong>olchain was built with the debug symbols kept, it will be also possible
for GDB <strong>to</strong> debug C library functions our application calls (so it might worth the disk space).
6.4 Migration between Minor Releases
6.4.1 Simple Upgrade
To migrate an existing project from within one minor release of the second main release <strong>to</strong> the next one (e.g.
2.0.0 <strong>to</strong> 2.0.x), we do the following steps:
~/my_bsp# ptxdist --force migrate
60

6 Various Aspects of Daily Work
6.5 Migration between Major Releases
6.5.1 Basic Conversion
To migrate an existing <strong>PTXdist</strong>-1 project <strong>to</strong> the new <strong>PTXdist</strong>-2 the following steps are <strong>to</strong> be done:
To convert a <strong>PTXdist</strong>-1 project in<strong>to</strong> a <strong>PTXdist</strong>-2 project simply copy your old ptxconfig file in<strong>to</strong> the files
selected_ptxconfig and selected_platform.
After that, run
~/my_bsp# ptxdist --force platformconfig
<strong>to</strong> configure the platform specific part and check if everything is set up correctly and save these settings. All in the
platform unused symbols will now be discarded and the remaining required symbols and their values are saved
<strong>to</strong> the selected_platform file.
Repeat the same step with
~/my_bsp# ptxdist --force menuconfig
In this case all for userland configuration unused symbols are discarded from the original ptxconfig file settings
and the remaining are saved <strong>to</strong> the selected_ptxconfig file. Check carefully if everything is set up correctly 1
Now you have successfully separated platform and userland configuration. This is the main configuration ptxdist-
2 uses in a single platform project.
6.5.2 Adaption of Rules Files
A few adaptions in the project local rules files are required, <strong>to</strong> also migrate them <strong>to</strong> the new <strong>PTXdist</strong> infrastructure.
Variables
The names of a few variables have changed.
• PTXCONF_HOST_PREFIX must be replaced by PTXCONF_SYSROOT_HOST
• PTXCONF_ARCH must be replaced by PTXCONF_ARCH_STRING
• IMAGEDIR must be replaced by PKGDIR
Local Source Handling
To retain the old behaviour of ptxdist-1 in handling local sources simply keep the _SOURCE variable
empty in the corresponding local source rule file.
1 At least if you are using Busybox as your shell environment you must check carefully if all settings in the previous Busybox version are
still present. Each version of Busybox changes various used symbolnames, so it could happen that some settings are lost during the
transition.
61

6 Various Aspects of Daily Work
6.5.3 <strong>PTXdist</strong>-1 Look and Feel
To keep the <strong>PTXdist</strong>-1 feeling use the following rules:
• Omit the platform name (e.g. keep this menu entry empty) when running pxtdist platformconfig
• Open the selected_platformconfig file with an edi<strong>to</strong>r and search for SYSROOT_TARGET, SYSROOT_HOST
and SYSROOT_CROSS. Replace their default settings with:
– For SYSROOT_TARGET: $PTXDIST_WORKSPACE/local/$PTXCONF_ARCH_STRING
– For SYSROOT_HOST: $PTXDIST_WORKSPACE/local-host
– For SYSROOT_CROSS: $PTXDIST_WORKSPACE/local-cross
With these settings you get the same direc<strong>to</strong>ry structure in a ptxdist-2 project as in ptxdist-1.
6.6 Software Installation and Upgrade
Root filesystems for Linux are usually built as a flash image and pushed in<strong>to</strong> the respective root medium. <strong>How</strong>ever,
when working with Embedded Linux systems, developers often have the need <strong>to</strong>
• install new packages
• remove packages
• update packages
• add configuration
Installation of new packages may for example happen if a developer works on a new piece of application code, or
if a new library is being written for the embedded system. Package updating may be a requirement even during
the system’s life cycle, for example for updating a cus<strong>to</strong>mer application in the field.
Conventional Linux distributions like Debian, SuSE or Fedora use package systems like RPM or DEB <strong>to</strong> organize
their software packages. Unfortunately, these methods require huge packet databases in the root system, which
is bad for space constrained embedded systems. So what we need is a packet system that
• offers installation/removement of packages
• has no big database but a very low overhead
• allows packet management features like pre/post scripts (i.e. shutdown a web server, then upgrade it and
start it again)
ipkg is such a packet system and it is being used in ptxdist. Originally developed for the IBM Itsy, ipkg is meanwhile
being used on all kinds of embedded Linux projects. The concept of ipkg archives is based on the well
known Debian packet management format: ipkg archives are “ar” archives, containing a tarball with the binary
files for the target box, plus management scripts which can be run on pre-install, post-install, pre-rm and postrm.
So even if no ipkg management utilities are available, developers can modify the archives with standard shell
and console <strong>to</strong>ols.
6.6.1 ipkg Usage in <strong>PTXdist</strong>
<strong>PTXdist</strong> end users and packet developers don’t have <strong>to</strong> care directly about ipkg. Packages are being created
during the targetinstall stage, then put in<strong>to</strong> the platform-versatilepb/packages/direc<strong>to</strong>ry. After the targetinstall
62

6 Various Aspects of Daily Work
stage of a packet was done, this direc<strong>to</strong>ry contains the ipkg packet itself plus, for most packages, a direc<strong>to</strong>ry with
the file content.
The ipkg packets contain the binaries for the root filesystem as well as start/s<strong>to</strong>p scripts and meta data about
the Unix filesystem permissions; when <strong>PTXdist</strong> creates the root filesystem which is later flashed in<strong>to</strong> the onboard
flash of an embedded system, it takes the information from the ipkg packets as the source, in order <strong>to</strong> make sure
that the image is consistent <strong>to</strong> what the packages contain.
Internally, <strong>PTXdist</strong> always uses ipkg packets <strong>to</strong> s<strong>to</strong>re it’s target data. <strong>How</strong>ever, the ipkg functionality is not always
exposed <strong>to</strong> the target itself. So in order <strong>to</strong> use packets, navigate <strong>to</strong> Disk and File Utilities and enable ipkg. In the
ipkg sub menu, make sure that the install /etc/ipkg.conf switch is active. This config file is necessary <strong>to</strong> make ipkg
work at runtime system.
The ipkg <strong>to</strong>ol can only be used in images created by ptxdist images. It’s not fully working within
the platform-versatilepb/root/ subdirec<strong>to</strong>ry used as NFS root filesystem.
6.6.2 Packet Installation
A common use case for ipkg packets is <strong>to</strong> push new software <strong>to</strong> an already deployed target. There must be
a communication channel <strong>to</strong> transfer the packet itself <strong>to</strong> the embedded system, i.e. by using FTP or a secure
connection via SFTP or SSH, so it has <strong>to</strong> be made sure that such a service is installed and configured on the target.
It is necessary that enough free space is available, in order <strong>to</strong> s<strong>to</strong>re the packet itself. A good rule of thumb is <strong>to</strong>
have twice the size of the installed package: while the packet is being installed, the archive as well as it’s contents
must fit in<strong>to</strong> the system s<strong>to</strong>rage. This may be a problem on space constrained systems.
If the packet was transferred, it is necessary <strong>to</strong> have remote shell access <strong>to</strong> the box, either via telnet or, if security
is an issue, by using SSH. It is also possible <strong>to</strong> au<strong>to</strong>mate this process by using an intelligent update mechanism.
The shell is being used <strong>to</strong> start the necessary commands. If the packet was installed, the ipkg archive can be
removed again.
6.6.3 Au<strong>to</strong>matic Packet Download
It is also possible <strong>to</strong> let the embedded system download ipkg packets au<strong>to</strong>matically from a network source, without
pushing the packets from the outside. In order <strong>to</strong> do so, a valid URL must be written in<strong>to</strong> the /etc/ipkg.conf
file. In this case one of the wget implementations in <strong>PTXdist</strong> must be selected, either the one in busybox (Shell &
Console Tools, BusyBox, Networking Utilities) or the native implementation (Networking Tools).
6.6.4 The ipkg Command
The following sections describe the ipkg features.
What’s Installed on the System?
To get a list of installed packages, use list_installed:
63

6 Various Aspects of Daily Work
# ipkg list_installed
busybox - 1.1.3 -
figlet - 222 -
gcclibs - 4.1.1 -
gdbserver - 6.4 -
glib - 2.8.6 -
glibc - 2.5 -
ipkg - 0.99.163 -
ixp-firmware - 1 -
kernel-modules - 2.6.18 -
libxml2 - 2.6.27 -
mc - 4.6.1 -
memedit - 0.7 -
ncurses - 5.5 -
pciutils - 2.2.1 -
pureftpd - 1.0.21 -
readline - 5.0 -
rootfs - 1.0.0 -
strace - 4.5.14-20061101 -
udev - 088 -
zlib - 1.2.3 -
Successfully terminated.
Content of a Package
To see what files are in an installed package, use files:
# ipkg files udev
Package udev (106) is installed on root and has the following files:
/etc/init.d/udev
/sbin/udevtrigger
/etc/udev/udev.conf
/etc/rc.d/S00_udev
/sbin/udevd
/sbin/udevsettle
Successfully terminated.
Adding a Package
Adding a new packet or replacing an already installed one is done by
# ipkg install .ipk
Note the trailing .ipk. This extension must be given if the package file is already part of the filesystem. Otherwise
ipkg tries <strong>to</strong> download it from the URL configured in /etc/ipkg.conf.
Removing a Package
To remove the contents of a package from the running system, ensure that nothing from the package is currently
in use. Find out the precise packet name with
64

6 Various Aspects of Daily Work
# ipkg list
and remove it’s contents from the runtime system with
# ipkg remove
Upgrading a Package
To upgrade a package, first remove it’s current contents from the runtime system. In a second step, install the
contents of the new ipkg package.
# ipkg list
# ipkg remove
# ipkg [.ipk]
6.7 Downloading Packages from the Web
Sometimes it makes sense <strong>to</strong> get all required source archives at once. For example prior <strong>to</strong> a shipment we want
<strong>to</strong> also include all source archives, <strong>to</strong> free the user from downloading it by him/herself.
<strong>PTXdist</strong> supports this requirement by the export_src parameter. It collects all required source archives in<strong>to</strong> one
given single direc<strong>to</strong>ry. To do so, the current project must be set up correctly, e.g. the select and platform commands
must be ran prior the export_src step.
If everything is set up correctly we can run the following commands <strong>to</strong> get the full list of required archives <strong>to</strong> build
the project again without a internet connection.
$ mkdir my_archives
$ ptxdist export_src my_archives
<strong>PTXdist</strong> will now collect all source archives <strong>to</strong> the my_archives/ direc<strong>to</strong>ry.
Note: If <strong>PTXdist</strong> is configured <strong>to</strong> share one source archive direc<strong>to</strong>ry for all projects, this step will simply copy the
source archives from the shared source archive direc<strong>to</strong>ry. Otherwise <strong>PTXdist</strong> will start <strong>to</strong> download them from
the world wide web.
65

7 Document Revisions
2010/01/08 Initial Revision
2010/01/11 Section ”Adding simple Files <strong>to</strong> the Build Process” added
2010/01/11 Section ”Variables reference” added
2010/01/20 Section ”Debugging with CPU emulation” added
2010/01/21 Section ”<strong>PTXdist</strong> parameter reference” added
2010/04/15 Section ”Adding new Packages” extended
2010/04/16 Section ”Using Existing Toolchains” extended
2010/05/20 Section ”Adding binary only Files” added
2010/05/20 Section ”Adding Files in<strong>to</strong> the Build” foldet in<strong>to</strong> ”Adding binary only Files”
2010/05/20 Section ”Adapting Userland Settings” extended
2011/01/27 Section ”Rule File Macro Reference”, ’install_tree’ documentation added
2011/01/27 Section ”Rule File Macro Reference”, ’install_alternative’ search order fixed
2011/01/27 Section ”Variables Reference”, some more useful variables added
2011/01/27 Section ”Adding new Packages”, documentation adapted <strong>to</strong> current ptxdist behaviour
×
66

8 Getting help
Below is a list of locations where you can get help in case of trouble. For questions how <strong>to</strong> do something special
with <strong>PTXdist</strong> or general questions about Linux in the embedded world, try these.
8.1 Mailing Lists
8.1.1 About <strong>PTXdist</strong> in Particular
This is an English language public mailing list for questions about <strong>PTXdist</strong>. See
http://www.pengutronix.de/mailinglists/index_en.html
how <strong>to</strong> subscribe <strong>to</strong> this list. If you want <strong>to</strong> search through the mailing list archive, visit
http://www.mail-archive.com/
and search for the list ptxdist. Please note again that this mailing list is just related <strong>to</strong> the <strong>PTXdist</strong> as a software.
For questions regarding your specific BSP, see the following items.
8.1.2 About Embedded Linux in General
This is a German language public mailing list for general questions about Linux in embedded environments. See
http://www.pengutronix.de/mailinglists/index_de.html
how <strong>to</strong> subscribe <strong>to</strong> this list. Note: You can also send mails in English.
8.2 News Groups
8.2.1 About Linux in Embedded Environments
This is an English newsgroup for general questions about Linux in embedded environments.
comp.os.linux.embedded
8.2.2 About General Unix/Linux Questions
This is a German newsgroup for general questions about Unix/Linux programming.
de.comp.os.unix.programming
67

8 Getting help
8.3 Chat/IRC
About <strong>PTXdist</strong> in particular
irc.freenode.net:6667
Create a connection <strong>to</strong> the irc.freenode.net:6667 server and enter the chatroom #ptxdist. This is an English
room <strong>to</strong> answer questions about <strong>PTXdist</strong>. Best time <strong>to</strong> meet somebody there is at European daytime.
8.4 Commercial Support
You can order immediate support through cus<strong>to</strong>mer specific mailing lists, by telephone or also on site. Ask our
sales representative for a price quotation for your special requirements.
Contact us at:
Pengutronix
Peiner Str. 6-8
31137 Hildesheim
Germany
Phone: +49 - 51 21 / 20 69 17 - 0
Fax: +49 - 51 21 / 20 69 17 - 55 55
or by electronic mail:
sales@pengutronix.de
68