Home

OSELAS.Support OSELAS.Training OSELAS

1. e reproducible Embedded developers usually want to know what s in their systems be it that they have to support their software for a long time span something like 10 15 years are usual product lifetimes in automation applications or that they have such a special scenario that they have to maintain their integrated source oftheir Userland themselves Entering PTXdist 8 f Pengutronix 2 Getting a working Environment SIMPLY EXPLAINED o x o Q o x 5 Q o LET ME TAKE A WILD GUESS int doSomething DOES SOMETHING SELF DOCUMENTING CODE 2 1 Download Software Components In order to follow this manual some software archives are needed There are several possibilities how to get these either as part of an evaluation board package or by downloading them from the Pengutronix web site f Pengutronix 9 2 Getting a working Environment The central place for OSELAS related documentation is http www oselas comand http www ptxdist de These websites provide all required packages and documentation at least for software components which are available to the public In order to build OSELAS BSP Pengutronix Generic 2014 07 0 the following source archives have to be available on the development host e ptxdist 2014 07 0 tar bz2 e OSELAS BSP Pengutronix Generic 2014 07 0 tar gz e ptxdist 2013 12 0 tar bz2 e OSELAS Toolchain 2013 12 2 tar bz2 If they are not available on the development system yet
2. PTXdist tries to find the right toolchain from data read from the platform configuration settings and a toolchain at opt that matches to these settings But that s for our convenience only If we decide to install the toolchains at a different location we still can use the toolchain parameter to define the toolchain to be used on a per project base 2 3 4 Building the OSELAS Toolchain for OSELAS BSP Pengutronix Generic 2014 07 0 installed to opt but must never be compiled in the opt directory You will get many funny Do the following steps in your own home directory HOME The final OSELAS Toolchain gets A error messages if you try to compile the OSELAS Toolchain in opt To compile and install an OSELAS Toolchain we have to extract the OSELAS Toolchain archive change into the new folder configure the compiler in question and start the build The required compiler to build the OSELAS BSP Pengutronix Generic 2014 07 0 board support package is 1586 unknown 1linux gnu_gcc 4 8 2_glibc 2 18_binutils 2 24_kernel 3 12 sanitized So the steps to build this toolchain are In order to build any of the OSELAS Toolchains the host must provide the tool fakeroot Other wise the message bash fakeroot command not found will occur and the build stops Please ensure the current directory the entry is not part of your PATH environment variable PTXdist tries to sort out this entry but might not be successful in doing so Check by ru
3. 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 lt me my org com gt 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 touch The header of this stage defines some information IPKG needs The important part that we must modify is the call to the install_copy macro refer to section 5 2 for more details about this kind of macros This call instructs PTXdist to include the given file with PID UID and permissions into the IPKG which means to install this file to the target s root filesystem From the previous install stage we know this package installs an executable called foo to location usr bin We can do the same for our target by changing the install_copy line to call install_copy foo 0 0 0755 FOO_DIR foo usr bin foo f Pengutronix 2 4 PTXdist Developer s Manual To check it we just run ptxdist targetinstall foo install_init install_init install_init install_init install_init install_init install_fixup install_fixup install_fixup install_fixup install_fixup install_fixup install_copy preparing for image creation ARCH gt 1
4. install ptxdist install foo target foo install 8 f Pengutronix i 4 PTXdist Developer s Manual make 1 Entering directory home jbe my_new_prj build target foo 1 1 0 make 2 Entering directory home jbe my_new_prj build target foo 1 1 0 make 3 Entering directory 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 directory home jbe my_new_prj build target foo 1 1 0 make 2 Leaving directory home jbe my_new_prj build target foo 1 1 0 make 1 Leaving directory home jbe my_new_prj build target foo 1 1 0 finished target foo install finished target foo install post This install stage does not install anything to the target root filesystem It is mostly intended to install libraries and header files other programs should link against later on The last stage targetinstall is the one that defines the package s components to be forwarded to the target s root filesystem Due to the absence of a generic way this is the task of the developer So at this point of time we must run our favourite editor again and modify our new rule file rules foo make The skeleton for the targetinstall stage looks like this STATEDIR foo targetinstall call targetinfo call install_init foo
5. patches directory at its main installation location This search order can be used to use specific patch series for specific cases 32 f Pengutronix 4 PTXdist Developer s Manual e platfom specific e project specific e common case bug fixing The bug fixing case is used in accordance to a replacement of a rule file If this was done due to a backport and the more recent PTXdist 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 PTXdist provides default configuration files for the most common cases These files can be found in the generic etc directory and they are using the same names as the ones at runtime and their install directory on the target side will also be etc But some of these default configuration files are empty due to 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 PTXdist first searches the project local projectroot etc directory for a specific configuration file and falls back to use the default one if none exists locally A popular example is the configuration file etc fstab The default one coming with PTXdist works for the most co
6. 1 Creating the Library Template Creating the library package can be done by the PTXdist s newpackage command jbe host gt ptxdist newpackage src autoconf lib ptxdist creating a new src autoconf lib package ptxdist enter package name ptxdist enter version number ptxdist enter package author ptxdist enter package section generating rules foo make generating rules foo in local_src foo does not exist create Y n Y olf internal name c h configure ac README COPYING Makefile am lib name pc in autogen s lib name h wizard sh h After this step the new directory local_src foo exists and contains various template files All of these files are dedicated to be modified by yourself The content of this directory is jbe host gt ls 1 local_src foo total 48 rw r r NE rw r r rwxr xr x SNE Wa Wal Wai W drwxr xr x jbe jbe jbe jbe jbe jbe jbe jbe jbe jbe ptx ptx ptx ptx ptx ptx ptx ptx ptx ptx 382 1768 1370 267 11947 708 428 185 331 4096 Jun Jun Jun Apr Jun Jun Jun Jun 18 18 18 16 18 18 18 18 18 18 6 10 2 Licence related stuff COPYING 23 00 COPYING 23 23 a6 16 2012 23 23 2332 23 23 23 16 16 00 6 6 16 Makefile am README autogen sh configure ac foo c internal h libfoo h libfoo pc in m4 You must think about the licence your library use
7. 1996 WHAT S THE DIFFERENCE 51 5 PTXdist Reference 5 1 Variables Reference The following variables are provided by PTXdist to simplify creating rule files Every developer should use these variables in every single line in the rule file to avoid any further adaption when external paths are changed To get their content related to the current project we can simply run a ptxdist print PTXDIST_TOPDIR usr local 1ib ptxdist 2014 07 0 Replace the PTXDIST_TOPDIR with one of the other generic variables PTXdist provides 5 1 1 PTXDIST_TOPDIR Points always to the installation directory of PTXdist 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 to a directory tree all cross relevant executables libraries and header files are installed to in the current project All of the project s packages built for the host to create data for the tar get are searching in this directory tree for their dependencies executables header and library files Use PTXDIST_SYSROOT_CROSS bin to install executables PTXDIST_SYSROOT_CROSS include for header files and PTXDIST_SYSROOT_CROSS 1ib for libraries 5 1 4 PTXDIST_SYSROOT_HOST PTXDIST_SYSROOT_HOST points to a directory tree all host relevant executables libraries and header files are installed to All project s packages built for the host are searching in
8. 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 to enter here URL of basedir This URL tells PTXdist where to download the source archive from the web if not already done If the full URL to 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 to be entered here suffix Archives are using various formats for distribution PTXdist uses the suffix entry to select the match ing extraction tool If the archive s full name is foo 1 1 0 tar gz then tar gz is the suffix to enter here package author If we intend to contribute this new package to PTXdist mainline we should add ourname here This name will be used in the copyright note of the rule file and will also be added to the generated ipkg When you run ptxdist setup prior to this call you can enter your name and your email address so PTXdist will use it as the default very handy if you intend to add many new packages package section We can enter here the menu section name where our new package menu entry should be listed 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 to get a new package The next steps to make it work are to check if al
9. Now everything is prepared for PTXdist to compile the BSP Starting the engines is simply done with ptxdist go PTXdist does now automatically find out from the selected_ptxconfig and selected_platformconfig files which packages belong to the project and starts compiling their targetinstall stages that one that actually puts the com piled binaries into the root filesystem While doing this PTXdist 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 directories in our project platform i586 build cross Contains all packages sources compiled to run on the host and handle target archi tecture dependend things platform i586 build host Contains all packages sources compiled to run on the host and handle architecture independend things platform i586 build target Contains all package sources compiled for the target architecure platform i586 images Generated files forthe target can be found here Kernel image and root filesystem image platform i586 packages Location for alle individual packages in ipk format platform i586 sysroot target Contains everything target architecture dependend libraries header files and so on platform i586 sysroot cross Contains everything that is host specific but must handle target architecture data platform i586 sysroot host Contains everything that is only host specific platform i586 root
10. PTXdist treats this package as an autotoolized package and runs STATEDIR package prepare call targetinfo call clean package _DIR config cache cd package _DIR package _SUBDIR 88 package _PATH package _CONF_ENV configure package _CONF_OPT call touch The package _CONF_OPT should at least be defined to CROSS_AUTOCONF_USR or CROSS_AUTOCONF_ROOT If the package s rule file defines package _CONF_TOOL to cmake FOO_CONF_TOOL cmake for our foo example PTXdist treats this package as a cmake based package and runs STATEDIR package prepare call targetinfo cd package _DIR amp amp package _PATH package _CONF_ENV cmake package _CONF_OPT call touch frengutronix 63 Pengutronix 5 PTXdist Reference The package _CONF_OPT should at least be defined to CROSS_CMAKE_USR or CROSS_CMAKE_ROOT If the package s rule file defines package _CONF_TOOL to qmake FOO_CONF_TOOL qmake for our foo example PTXdist treats this package as a qmake based package and runs STATEDIR package prepare call targetinfo cd package _DIR amp amp package _PATH package _CONF_ENV qmake package _CONF_OPT call touch The package _CONF_OPT should at least be defined to CROSS_QMAKE_OPT compile Stage Default Rule If the compile stage is omitted PTXdist runs instead STATEDIR package compile call ta
11. Proxy Setup To do so an internet access is required If this access is managed by a proxy wget command must be adviced to use it PTXdist can be configured to advice the wget command automatically Navigate to entry Proxies and enter the required addresses and ports to access the proxy in the form lt protocol gt lt address gt lt port gt Source Archive Location Whenever PTXdist downloads source archives it stores these archives in a project local manner This is the default behaviour If we are working with more than one PTXdist based project every project would download its own required archives in this case To share all source archives between all projects PTXdist can be configured to share only one archive directory for all projects it handles Navigate to menu entry Source Directory and enter the path to the directory where PTXdist should store archives to share between its projects Generic Project Location If we already installed the generic projects we should also configure PTXdist to know this location If we already did so we can use the command ptxdist projects to get a list of available projects and ptxdist clone to get a local working copy of a shared generic project Navigate to menu entry Project Searchpath and enter the path to 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 PTXdist s generic projects and our own previous projec
12. Target s root filesystem image This directory can be mounted as an NFS root for example platform i586 root debug Target s root filesystem image The difference to root is all programs and libraries in this directory still have their debug information present This directory is intended to be used as system root for a debugger To be used by the debugger you should setup your debugger with set solib absolute prefix lt path to workspace gt root debug platform i586 state Building every package is divided onto stages And stages of one package can depend on stages of other packages In order to handle this correctly this directory contains timestamp files about finished stages This are the generated files platform i586 logfile Every run of PTXdist will add its output to this file If something fails this file can help to find the cause frengutrono 24 Pengutronix 3 PTXdist User s Manual 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 to the target system or copied on some kind of disk media To do so we just run ptxdist images PTXdist now extracts the content of priorly created ipk packages to a temporary directory and generates an image out of it PTXdist supports following image types e hd img contains bootloader kernel and root files in an ext2 partition Mostly used for X86 target systems e root jffs2 root files inside a jff
13. VCCI AC 5 45 Support OSELAS Training OSELAS Development OSELAS Services tin fraud a How to become a PTXdist Guru ng ay Based on the OSELAS BS P po ay Pengutronix Generic x86 Pengutronix k Pengutronix e K Peiner Stra e 6 8 31137 Hildesheim 49 0 51 21 20 6917 o Fon 49 0 5121 20 69 17 55 55 Fax info pengutronix de 2014 Pengutronix Hildesheim GIT Rev 4fbf6a5016ad gt IUBd 1 UOg 2 10 UOW INO uo 43135 pue 3193H IN Contents 1 Welcome to the Embedded World 1 1 First Steps in the Embedded World 1 2 From Server to Embedded 1 3 Linux Embedded Linux 2 Getting a working Environment 2 1 Download Software Components 2 2 PTXdist Installation 221 Main ParisofP Xd kde eas Gees eee ede a bd ee 222 Extracting the Sources o sco one me eae a WE a ee 237 UP MOTSOUIGHOS y sd ek Ge ee 2 Sane Mala Ge ae ee ete ete de lao E 22A Contidurne RIAU oo eeo SG Se e Ee ee ee G Da TOIS aa ona aos as ta a Stes SF BSR 2 aes 8 Eee 2 3 1 Using existing Toolchains from different Vendors 1 ee ee ee 2 3 2 Omitting buildingaToolchain lt o ooo ee 23 3 Buildinga Toolchain is s s sacda 2 edd a a dae ae ed 2 3 4 Building the OSELAS Toolchain for OSELAS BSP Pengutronix Generic 2014 07 0 29 5 Protecting the Todlehait copados RAH ae Re ee a eS ee ae ee 2 3 6 Building additional Toolchains o ooo ee 3 PTXdist User s Manual 3 1 How do
14. a OR eee Ae bees 56 5 2 6 install_alternative_tree 2 ee 57 527 installaltemative ono s docta a a dor a ee eae ES He eee 57 528 Install oo co 322526 2G bebe ee Reda Gene eee wee hed oS 58 209 JInstallearchive issig 644i u she bebe Ra Ree Ree ee he Yee ea Ss 59 5210 Iistallllib 4 ic cei ew iw eee eee be tev hd oe bid dee ee eee oe 60 ei eS s os a Ghee oA eo HRS Yee a eo Bo ee A 60 PAR POGUE p a o f era Bara c OREM EE Se eek ee oa oo a 61 Haa PUP WWO io a Ee ae le ew we me A a ee a E 61 Gu POOE en fo dew a ee ee ee a ad eb es ee ee 62 53 Rulefilelayout s wos sa a d 5 2836644 a a Ee ee ee we ee 62 5 3 1 Defaultstagerules lt ocacion woa ion a aa a a ee 62 So SkipphngasStage 2 vase taaie A a e a e ee E 65 5 4 PTXdist parameter reference ee 65 5 4 1 Setup and Project Actions a s pie ee E a a 65 SAS BUIGACIONS 2 coe eae pl ae ba ike ek i eh ne ee Ge Ge 66 43 Clean ACHONS lu rar a ea Re eee Be a ie 66 f Pengutronix 3 Contents 6 Various Aspects of Daily Work 67 6 1 Using an External Kernel Source Tree o o 67 6 1 1 Cloning the Linux Kernel Source Tree o o 67 6 1 2 Configuring the PTXdist Project o o o 67 Di WG 24 06 sra are eee A a e Se o ie e 68 6 2 Discovering Runtime Dependencies e e ee 68 6 2 1 Dependencies on Shared Libraries e ee 69 6 2 2 Dependencies
15. a new product was a good toolchain consisting of e acompiler e maybe an assembler e 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 to do his project with the more and more well known system The controllers had legacy interfaces like RS232 i2c or SPI which connected them to 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 micro controllers headless devices with just a few pins and very limited computing power and full blown micropro cessors System structures became much more complicated where our good old controllers have had just some interrupts with some small interrupt service routines we today need complicated generic interrupt infrastruc tures suitable for generic software frameworks Where we ve had some linearly mapped flash ROM and some data RAM we today 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 po
16. a project can support more than one platform this will configure the currently selected platform The short form for this action is kernelconfig PPengutronix 65 Pengutronix 5 PTXdist Reference menuconfig barebox this action starts the configure menu for the selected bootloader It depends on the platform settings which bootloader is enabled and to be used as an argument to the menuconfig action parameter Due toa project can support more than one platform this will configure the bootloader of the currently selected platform 5 4 2 Build Actions go this action will build all enabled packages in the current project configurations platform and user land 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 images most of the time this is the last step to get the required files and or images for the target It creates filesystems or device images to be used in conjunction with the target s filesystem media The result can be found in the images directory of the project or the platform directory 5 4 3 Clean Actions clean the clean action will remove all generated files while the last go run all build packages and root filesystem directories Only the selected configuration files are left untouched This is a way to start a fresh build cycle clean root this action will only clean the root filesystem
17. al This is a Pengutronix Quickstart Manual Copyright Pengutronix e K All rights reserved Pengutronix e K Peiner Str 6 8 31137 Hildesheim Germany Phone 49 51 21 20 69 17 0 Fax 49 51 21 20 69 17 55 55 Pengutronix
18. directories All the build directories are left untouched Using this action will re generate all ipkg opkg archives from the already built packages and also the root filesys tem directories in the next go action The clean root and go action is useful if the targetinstall stage for all packages should run again clean lt package gt this action will only clean the dedicated lt package gt It will remove its build directory and all installed files from the corresponding sysroot directory distclean the distclean action will remove all files that are not part ofthe main project It removes all generated files and directories like the clean action and also the created links in any platform and or select action 66 f Pengutronix 6 Various Aspects of Daily Work 6 1 Using an External Kernel Source Tree This application note describes how to use an external kernel source tree within a PTXdist 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 officially Linux kernel development tree jbe octopus git clone git git kernel org pub scm linux kernel git torvalds linux git sal jbe octopus ls 1 Exa drwxr xr x 38 jbe ptx 4096 2011 11 16 10 21 myprj drwxr xr x 25 jbe ptx 4096 2011 11 16 10 42 linux Ea 6 1 2 Configuring the PTXdist Project Note assumption is here the directory myprj contains a valid PTXdist project T
19. files to the m4 directory This will enable any user of your library to re generate the autotools based files without providing all dependencies by themself 6 10 6 Library related files README Prepared file with some information about the library you provide Be kind to the users of your library and write some sentences about basic features and usage of your library how to configure it and how to build it libfoo h This file will be installed It defines the API your library provides and will be used by other applications internal h This file will not be installed It will be used only at build time of your library 86 f Pengutronix 6 Various Aspects of Daily Work foo c The main source file of your library Keep in mind to mark all functions with the DSO_VISIBLE macro you want to export All other functions are kept internaly and you cannot link against them from an external application Note debugging is hard when all internal functions are hidden Forthis case you should configure the libary with the disable hide or with enable debug which includes switching off hiding functions 6 11 Frequently Asked Questions FAQ Q PTXdist does not support to generate some files in a way need them What can do A Everything PTXdist builds is controlled by package rule files which in fact are Makefiles rules x make If you modify such a file you can change it s behaviourin a way you need Itis generally no goo
20. handle this kind of packages We only have to 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 touch To compile the package we can use make s feature to 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 To use only make instead of the autotools we must instruct PTXdist to not use them by defining FOO_CONF_TOOL NO make will be called in this case with cd FOO_DIR amp amp 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 to forward the re quired settings to 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 6 f Pengutronix 3 4 PTXdist Developer s Manual 4 2 4 Patching Packages There can be various reasons why a package must be patched e Package is broken for cross compile environments e Package is broken within a specific feature e Package is vulnerable and needs some fixes e or anything else this cas
21. is also used to locate the source For our foo example package if we give lt destination gt as usr bin foo PTXdist copies the file platform i1586 packages foo 1 1 0 usr bin foo The lt strip gt is a complete optional parameter to prevent this macro from the regular stripping process it does on files Most of the cases stripping debug information from files is intended But some kind of files getting destroyed when this stripping happens to them One example is a Linux kernel module If it gets stripped it can t be loaded into the kernel anymore full strip fully strip the file while installing when this parameter is y or not given at all default case partially strip only strips real debug information from the file when this parameter is k Useful to keep Linux kernel module loadable at run time no strip preserve the file from being stripped when this parameter is one of the following o n no N or NO Due to the complexity of this macro here are some usage examples Create a directory in the root filesystem call install_copy foo 0 0 0755 home user foo Copy a file from the package build directory to the root filesystem f Pengutronix 5 PTXdist Reference call install_copy foo 0 0 0755 FOO_DIR foo usr bin foo Copy a file from the package build directory to 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 ins
22. is set this macro expands to the string with if unset to without instead Usage call ptx wwo lt variable gt lt parameter gt An example FOO_CONF_OPT call ptx wwo FOO_VARIABLE something Depending on the state of FOO_VARIABLE this line results into FOO_CONF_OPT with something if FOO_VARIABLE is set FOO_CONF_OPT without something if FOO_VARIABLE is unset 61 f Pengutronix 5 PTXdist Reference 5 2 14 ptx ifdef To convert the state set unset of a variable into one of two strings use the ptx ifdef macro If the given lt vari able gt is set this macro expands to the first given string if unset to the second given string Usage with something call ptx ifdef lt variable gt lt first string gt lt second string An example FOO_CONF_OPT with something call ptx ifdef FOO_VARIABLE usr none Depending on the state of FOO_VARIABLE this line results into FOO_CONF_OPT with something usr if FOO_VARIABLE is set FOO_CONF_OPT with something none if FOO_VARIABLE is unset 5 3 Rule file layout Each rule file provides PTXdist with the required steps to be done ona per package base e get extract prepare compile install targetinstall 5 3 1 Default stage rules As for most packages these steps can be done in a default way PTXdist provides generic rules for each package If a package s rule file does not provide a specific stage rule the default
23. it is necessary to get them The PTXdist 2013 12 0 is only required to build the toolchain while PTXdist 2014 07 0 is re quired to build the BSP All PTXdist revisions can co exist 2 2 PTXdist Installation The PTXdist build system can be used to create a root filesystem for embedded Linux devices In order to start development with PTXdist it is necessary to install the software on the development system This chapter provides information about how to install and configure PTXdist on the development host 2 2 1 Main Parts of PTXdist The most important software component which is necessary to build an OSELAS BSP board support package is the ptxdist tool So before starting any work we ll have to install PTXdist on the development host PTXdist consists of the following parts The ptxdist Program ptxdist is installed on the development host during the installation process ptxdist is called to trigger any action like building a software packet cleaning up the tree etc Usually the ptxdist program is used in a workspace directory which contains all project relevant files A Configuration System The config system is used to customize a configuration which contains information about which packages have to be built and which options are selected Patches Due to the fact that some upstream packages are not bug free especially with regard to cross compi lation it is often necessary to patch the original software PTXdist co
24. revision gt target In the kernel config file menu entry you should enter kernelconfig PTXCONF_KERNEL_VERSION target Whenever you change the linux kernel Version menu entry now this will ensure using a different kernel config file too Q I m trying to use a JAVA based package in PTXdist But compiling fails badly Does it ever work at Pengutronix A This kind of packages only build correctly when an original SUN VM SDK is used Run PTXdist setup and point the Java SDK menu entry to the installation path of your SUN JAVA SDK Q made a new project and everythings seems fine But when I start my target with the root filesystem generated by PTXdist it fails with cannot run etc init d rcS No such file or directory A The error message is confusing But this script needs bin sh to run Most of the time this message occures when bin sh does not exists Did you enable it in your busybox configuration Q have created a path for my source archives and try to make PTXdist use it But whenever run PTXdist now it fails with the following error message usr local bin ptxdist archives command not found 88 f Pengutronix 6 Various Aspects of Daily Work A In this case the path was HOME source archives which includes a whitespace in the name of the directory to store the source archives in Handling directory or filenames with whitespaces in applications isn t trivial and also PTXdist suffers all over the place fro
25. stage rule will be used instead Omitting one of the stage rules does not mean that PTXdist skips this stage In this case the default stage rule is used instead get Stage Default Rule Ifthe get stage is omitted PTXdist runs instead STATEDIR package get call targetinfo call touch 62 f Pengutronix 5 PTXdist Reference Which means this step is skipped Ifthe 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 PTXdist runs instead STATEDIR package extract call targetinfo call clean package _DIR call extract package call patchin package call touch Which means a current existing directory of this package will be removed the archive gets freshly extracted again and if corresponding patches are found patched prepare Stage Default Rule If the prepare stage is omitted PTXdist runs a default stage rule depending on some variable settings If the package s rule file defines package _CONF_TOOL to NO this stage is simply skipped All rules files shall create the package _CONF_ENV variable and define it at least to CROSS_ENV if the prepare stage is used Ifthe package s rule file defines package _CONF_TOOL to autoconf FOO_CONF_TOOL autoconf for our foo exam ple
26. this directory tree for their depen dencies executables header and library files Use PTXDIST_SYSROOT_HOST bin to install executables PTXDIST_SYSROOT_HOST include for header files and PTXDIST_SYSROOT_HOST 1ib for libraries 5 1 5 PTXDIST_SYSROOT_TARGET PTXDIST_SYSROOT_TARGET points to a directory tree all target relevant libraries and header files are installed to All project s packages built for the target are searching in this directory tree for their dependencies header and library files These files are for compile time only for example to 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 52 f Pengutronix 5 PTXdist Reference 5 1 6 CROSS_PATH Use to find cross tools This path must be used to create anything that depends on the target s architecture but needs something running on the host to do the job Examples Creating a jffs2 image from the target s root filesystem This will need a tool running on the host but it will create data or code that runs on or is used on the target Building a library forthe target If this library needs other resources to be built other libraries its configure finds the right information in this path 5 1 7 HOST_PATH Used to find host tools This path must be used to create anything that not depends on the architecture
27. to download the source archive If it fails we should check our network connection proxy setup or if the given URL in use is correct Note Sometimes we do not know the content of all the other variables in the rule file To get an idea what content a variable has we can ask PTXdist about it ptxdist print FOO_URL http www foo com download src foo 1 1 0 tar gz 36 f Pengutronix 4 PTXdist Developer s Manual The next step would be to extract the archive But as PTXdist checks the MDs sum in this case this step will fail because the FOO_MD5 variable is still empty Let s fill it md5sum global_src foo 1 1 0 tar gz 92098402b775a139ebb00f57a587b447 This string must be assigned to the FOO_MDs in our new foo make rule file FOO_MD5 9a09840ab775a1 39ebb00f57a587b447 We are now prepared for the next step ptxdist extract foo extract archive global_src foo 1 1 0 tar gz extract dest home jbe my_new_prj build target PATCHIN packet fo00 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 autotoolized source package E g to prepare the build the archive comes with a configure script This is the default case for PTXdist So there is no need to modify the rule file and we can simply run ptxdist prepare foo checking build s
28. toolchain building step with PTXdist may be omitted The OSELAS BoardSupport Packages shipped for PTXdist have been tested with the OSE LAS Toolchains built with the same PTXdist version So if an external toolchain is being used which isn t known to be stable a target may fail Note that not all compiler versions and combi nations work properly in a cross environment Every OSELAS BoardSupport Package checks for its OSELAS Toolchain it s tested against so using a toolchain from a different vendor than OSELAS requires an additional step Open the OSELAS BoardSupport Package menu with frengutrono 14 Pengutronix 2 Getting a working Environment ptxdist platformconfig and navigate to architecture gt toolchain and check for specific toolchain vendor Clear this entry to disable the toolchain vendor check Preconditions a toolchain from a different vendor than OSELAS must meet e it shall be built with the configure option with sysroot pointing to its own C libraries e it should not support the multilib feature as this may confuse PTXdist which libraries are to select for the root filesystem If we want to check if our toolchain was built with the with sysroot option we just run this simple command mytoolchain gcc v 2 gt 81 grep with sysroot If this command does not output anything this toolchain was not built with the with sysroot option and cannot be used with PTXdist 2 3 2 Omitt
29. 08d42e8eccf 20de61e05 e 2 6 38 7d471477bf267546f902da62227fa976 e 2 6 37 c8ee37b4fdccdb651e0603d35350b434 28 f Pengutronix 3 PTXdist User s Manual Now we can leave the menu and save the new settings A Linux kernel needs a configuration for being built correctly The OSELAS BSP Pengutronix Generic 2014 07 0 project comes with a prepared configuration in the file configs i586 qemu kernelconfig 3 for the 3 0 kernel It is always a good idea to start with a known to work kernel configuration So for this example we are using a different known to work kernel configuration in the configs i586 qemu kernelconfig 3 7 file for our new 3 7 kernel 3 3 3 Adapting Linux Kernel Settings In this section we want to show how to change some Linux kernel settings of our OSELAS BSP Pengutronix Generic 2014 07 0project First of all we run ptxdist menuconfig kernel This command will start the kernel s Kconfig For this example we want to enable USB host support in the kernel To do so we navigate to Device Drivers gt USB support gt lt gt Support for Host side USB lt gt OHCI HCD support Note All the listed empty and lt gt above must be activated to 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 not
30. 2 Maket Work 662240688 A884 A G4 a a e ee 35 4 2 3 Advanced Rule Files c sec ce rnana nrs sra ten 41 424 Patching Packages ge eae nia ia Age A wl a ee gw A 47 4 2 5 Creating Patches for a Package 2 2 ee 4 47 4 2 6 Modifying Autotoolized Packages nononono ee 48 a3 Adding Bina On RIES sosa sa s a acii a aiani ee a eb da 49 431 Oldstyle singleties lt sousi ee a a ee ee see ee ee 49 4 3 2 New style using archives e 49 233 Creating a RulesFile costos a aa a a e a a e a a a a e e 50 5 PTXdist Reference 51 Bap Variables References isa a Ra A a as 52 sit PTXDIST_TOPDIR a iocona a a e a a kw a 52 5 1 2 PTXDIST_WORKSPACE o 52 sa3 PTXDIST_SYSROOT_CROSS 2 0 240d dw ee we eww eee ea ew en 52 5 4 PTXDIST_SYSROOT_HOST 4 oak beh ae bbw Se aa OES RES 52 5 15 PTXDIST_SYSROOT_TARGET 2 626 ce cee ee ee eee ees 52 tO CROSSO PATH eet e ee eh are e aS Re a a ae el oe a RO Pe G 53 eh a oC st od a O RA A E aak A A Re G 53 558 RODTRIR lt i mira da aoa AR da A 53 5 1 9 PTXCONF_PLATFORM you o e e a a eee wees 53 5 1 10 PTXDIST_PLATFORMSUFFIX 0 0 cee ee ee ee 53 5 111 PTXDIST_PLATFORMCONFIGDIR o a 26 eee Be eee ee ee ew 53 5 1 12 PTXDIST_PLATFORMDIR sock oe ba bad oboe Eo eke e hae ER 53 5 2 RuleFile Macro Reference ee 53 A A EN A 54 A O A A A PO ee RS end 54 a Hs A a aed A A 54 CE MAAGD o o a AR A a we a doe bee be 54 eR CTSA BO o oa bee afb ee a atk
31. 386 done preinst not available postinst not available prerm not available postrm not available PACKAGE gt foo done PRIORITY gt optional done VERSION G gt 1 1 0 done SECTION G gt base done AUTHOR gt My Name lt me my org com gt done DESCRIPTION G gt missing done 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 xpkg_finish collecting license unknown done creating ipkg package done finished target foo targetinstall 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 PTXdist s menu hierarchy PTXdist arranges its menus on the meaning of each package Is ita network related tool Ora scripting language Ora graphical application Each of these global meanings have their own submenu where we can add our new entry to We just have to edit the head of our new menu file rules foo in to add it to a specific global menu If our new package is a network related tool the head ofthe menu file should look like SECTION networking We can grep through the other menu files from the PTXdist main instal
32. 5 1 8 ROOTDIR ROOTDIR points to the root of the target s root filesystem in the current project Used in very rare cases to create strange packages based on data in target s root filesystem for example 5 1 9 PTXCONF_PLATFORM PTXCONF_PLATFORM expands to 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 to the name of the currently selected platform but with a leading dot This is used in various files PTXdist should search for 5 1 11 PTXDIST_PLATFORMCONFIGDIR PTXDIST_PLATFORMCONFIGDIR points to the directory tree of the currently selected platform This path is used in various search functions 5 1 12 PTXDIST_PLATFORMDIR PTXDIST_PLATFORMDIR points to the directory build tree of the currently selected platform 5 2 Rule File Macro Reference Rules files in PTXdist are using macros to get things work Its highly recommended to use these macros instead to do something by ourself Using the macros is portable and such easier to maintain in the case a project should be upgraded to a more recent PTXdist version This chapter describes the predefined macros in PTXdist and their usage f Pengutronix 53 5 PTXdist Reference Whenever one of the macros installs something to the target s root filesystem it also accepts user and group IDs which are common in all filesysems Linux supports These IDs can be given as numeri
33. 55 FOO_DIR bar usr bin bar endif call install_finish foo call touch j Pengutronix 38 4 PTXdist Developer s Manual 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 PTXdist 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 to a missing external dependency For example El checking whether zlib exists failed In this example our new package depends on the compression library zlib PTXdist comes with a target zlib All we need to do in this case is to 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 PTXdist now builds the zlib first and our new package thereafter Managing External Compile Time Dependencies on Demand It is good practice to add only those dependecies that are really required for the current configuration of the package If the package provides the featu
34. 96 Jul 1 15 12 projectroot drwxr xr x 3 jb users 4096 Jul 1 15 12 rules Notes about some of the files and directories 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 directory contains the Quickstart you are currenly reading in configs A multiplatform BSP contains configurations for more than one target This directory contains the re spective 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 PTXdist installation will fit the needs But if not customized files are located in this directory rules If something special is required to build the BSP for the target it is intended for then this directory contains these additional rules patches If some special patches are required to build the BSP for this target then this directory contains these patches on a per package basis tests Contains test scripts for automated target setup Next we will build the OSELAS BSP Pengutronix Generic 2014 07 0 to show some of PTXdist s main features 3 2 2 Selecting a Userland Configuration First of all we have to select a userland configuration This step defines what kind of applications will be built for the hardware platform The OSELAS BSP Pengutron
35. But also this PTXdist feature must handle with care and so it is not enabled and used as default This section describes how to make use of this PTXdist feature and what pitfalls exists when doing so 6 8 2 Creating pre build archives To make PTXdist creating pre build archives enable this feature prior a build in the menu ptxdist menuconfig Project Name amp Version gt x create pre build archives Now run a regular build of the whole project ptxdist go When the build is finished the directory platform i586 packages contains additional archives files with the name scheme x dev tar gz These files are the pre build archives which PTXdist can use later on to re build the project 6 8 3 Using pre build archives To make PTXdist using pre build archives enable this feature prior a build in the menu ptxdist menuconfig Project Name 8 Version gt x use pre build archives lt some path to the archives gt With the next build e g ptxdist go PTXdist will look for a specific package if its corresponding pre build archive does exist Ifit does exist and the used hash value in the pre build archive s filename matches PTXdist will skip all source archive handling extract patch compile and install and just extract and use the pre build archive s content A regular and save usecase of pre build archives is e using one pre build archive pool for one specific PTXdist project e using a constant PTXdist ve
36. ES in the configure ac file Makefile am Special hints SUBDIR if your project contains more than one sub directory to build add these directories here Keep in mind these directories are visited in this order but never in parallel so you must handle dependencies manu ally _CPPFLAGS _CFLAGS _LIBADD if your library has some optional external dependencies add them on demand external libraries for example Keep in mind to not mix CPPFLAGS and CFLAGS additions And do not add these additions fixed to the _CPPFLAGS and _CFLAGS variables let configure do it in a sane way Whenever you want to forward special things to the _CPPFLAGS and _CFLAGS don t forget to add the AM_CPPFLAGS and AM_CFLAGS else they get lost Never add libraries to the _LDFLAGS variable Always add them to the _LIBADD variable instead This is important because the autotools forward all these variable based parameters in a specifc order to the tools compiler and linker 6 10 4 Template file for pkg config libfoo pc in This file gets installed to support the pkg config tool for package management It contains some important infor mation how to use your library and also handles its dependencies Special hints Name A human readable name for the library 8 f Pengutronix 5 6 Various Aspects of Daily Work Description add a brief description of your library here Version the main revision ofthe library Will automatically replaced from
37. 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 to dependencies into other selected entries are marked with a leading e Some entries need a free text to 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 PTXdist configuring menus To handle them they are divided and separated into 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 PTXdist can build the DDD debugger to debug applications running on the target e Root Filesystem Settings to arrange target s root filesystem and to select the main C runtime library Applications Everything we like to run on your target The main building blocks in the platform configuration menu are e Architecture Basic settings like the main and sub architecture the target system uses the toolchain to be used to build everything and some other architecture dependent settings gt 27 fPengutronnx 3 PTXdist User s Manual e Linux kernel Which kernel revision and kernel configuration should be used e Bootloader Which bootloader if any should be built in the project e The kind of image to populate a root filesystem into the target system The main
38. Leaving the emulated environment happens by entering the key sequence CTRL A X in the development host console PPengutronix 25 Pengutronix 3 PTXdist User s Manual 3 3 Adapting the OSELAS BSP Pengutronix Generic 2014 07 0 Project Handling a fully prepared PTXdist project is easy But everything is fixed to the settings the developer selected We now want to adapt the OSELAS BSP Pengutronix Generic 2014 07 0 project in a few simple settings 3 3 1 Working with Kconfig Whenever we modify our project PTXdist is using Kconfig to manipulate the settings Kconfig means kernel con figurator and was mainly developed to configure the Linux kernel itself But it is easy to adapt to use and so popular that more and more projects are using Kconfig for their purposes PTXdist is one of them What is Kconfig It is a user interface to 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 to organize them in a hierarchical manner solves challenges like resource dependencies supports help and search features PTXdist uses all of these features Kconfig supports a text based user interface by using the ncurses library to manipulate the screen content and should work on nearly all host systems For example running PTXdist s menuconfig subcommand in this way ptxdist menuconfig will show the following console output Navigate in Kco
39. TXdist handles toolchain building as a simple project like all other projects too So we can download the OSELAS Toolchain bundle and build the required toolchain for the OSELAS BoardSupport Package Building any toolchain of the OSELAS Toolchain 2013 12 2 is tested with PTXdist 2014 07 0 Pengutronix recommends to use this specific PTXdist to build the toolchain So it might be essential to install more than one PTXdist revision to build the toolchain and later on the Board Support Package if the latter one is made for a different PTXdist revision A PTXdist project generally allows to build into some project defined directory all OSELAS Toolchain projects that come with PTXdist are configured to use the standard installation paths mentioned below 16 f Pengutronix 2 Getting a working Environment All OSELAS Toolchain projects install their result into opt OSELAS Toolchain 2013 12 2 Usually the opt directory is not world writeable So in order to build our OSELAS Toolchain into that directory we need to use a root account to change the permissions PTXdist detects this case and asks if we want to run sudo to do the job for us Alternatively we can enter mkdir opt OSELAS Toolchain 2013 12 2 chown lt username gt opt OSELAS Toolchain 2013 12 2 chmod atrwx opt OSELAS Toolchain 2013 12 2 We recommend to keep this installation path as PTXdist expects the toolchains at opt Whenever we go to select a platform in a project
40. ailing list is just related to the PTXdist as a software For questions regarding your specific BSP see the following items 9 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 on how to subscribe to this list Note You can also send mails in English 9 2 About Working on the Linux Kernel The book Linux Kernel in a Nutshell from Greg Kroah Hartman Its online version can be read here http www kroah com 1kn 9 3 Chat IRC About PTXdist in particular irc freenode net 6667 Create a connection to the irc freenode net 6667 server and enter the chatroom ptxdist This is an English room to answer questions about PTXdist Best time to meet somebody there is at European daytime 92 f Pengutronix 9 Getting help 9 4 Commercial Support You can order immediate support through customer 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 5121 20 6917 0 Fax 49 51 21 20 69 17 55 55 or by electronic mail sales pengutronix de f Pengutronix 93 Eto gp t my mji mT quit fuli pilil iii fh iiin q n An 4 pal pl pl vilo atin fale ael
41. ainst the 1ibm from the toolchain But in this case the 1ibm must also be available in the target s root filesystem to fulfil the runtime dependency We have to force PTXdist to install libm 1ibmis part of the glibc package but is not installed by default to keep the root filesystem small So it does not help to select the GLIBC symbol to get a libmat runtime The correct solution here is to add a select LIBC_Mto 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 f Pengutronix a 4 PTXdist Developer s Manual 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 Note There are other packages around that do not install everything by default If our new package needs something special we musttake a look into the menu ofthe other package how to force the required components to be installed and add the corresponding selects to our own menu file In this case it does not help to enable the required parts in our project configuration because this has no effect on the build order Managing Non Autotool Packages Many packages are still coming with a plain Makefile The user has to adapt it to make it work in a cross compile environment as well PTXdist can also
42. amic linker prints the missing library to the console To check at build time if all other dependencies are present is easy too The architecture specific readelf tool can help us here It comes with the OSELAS Toolchain and is called via i586 unknown linux gnu readelf this example uses the one coming with the i586 unknown linux gnu toolchain To test the foo binary from our new package FOO we simply run 1586 unknown linux gnu readelf d platform i586 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 too It is also a way to 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 to run due to missing files directories or device nodes Often the error message if any that the binary creates in this case is ambiguous Here the strace tool can help us namely to 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 tools which PTXdist provides in its Debug Tools menu After adding strace to the root filesystem we can use it and obse
43. ary for the ARM architecture we have to use the cross compiler instead ofthe native one arm softfloat linux gnu gcc test c o test Also part of what we consider to be the toolchain 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 to the kernel The compiler and libc are very tightly coupled components the second stage compiler which is used to build normal user space code is being built against the libc itself For example ifthe target does not contain a hardware floating point unit but the toolchain generates floating point code it will fail This is also the case when the toolchain builds code for i686 CPUs whereas the target is i586 So in order to make things working consistently it is necessary that the runtime libc is identical with the libc the compiler was built against PTXdist doesn t contain a pre built binary toolchain Remember that it s not a distribution but a development tool But it can be used to build a toolchain for our target Building the toolchain usually has only to be done once It may be a good idea to 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 from different Vendors Ifa toolchain from a different vendor than OSELAS is already installed which is known to be working the
44. at form i586 root e the project s platform i586 root debug e an ipkg opkg packet in the project s platform i586 packages The parameters and their meanings lt package gt Name of the IPKG OPKG the macro should work on lt UID gt User ID the file should use in the target s root filesystem lt GID gt Group ID the directories and files should use in the target s root filesystem lt permission gt Permission as an octal value the library should use in the target s root filesystem mostly 0644 lt libname gt Basename of the library without any extension and path The install_lib macro searches for the library at the most common directories lib and usr lib And it searches always in the package s corresponding directory in platform i586 packages It also handles all re quired links to make the library work at runtime An example Lets assume the package foo 1 0 0 has installed the library libfoo into its platform 1586 packages foo 1 0 0 at e the lib platform 1586 packages foo 1 0 0 usr lib libfoo1 so 0 0 0 e first link platform 1586 packages foo 1 0 0 usr lib libfoo1 so 0 e second link platform i586 packages foo 1 0 0 usr lib libfoo1 so To install this library and its corresponding links the following line does the job call install_lib foo 0 0 0644 libfoo1 Note The package s install stage must be DESTDIR aware to be able to make it install its content into the cor responding packages directory i
45. ated during the targetinstall stage then put into the platform i586 packages directory After the targetinstall stage of a packet was done this directory contains the ipkg packet itself plus for most packages a directory with the file content The ipkg packets contain the binaries for the root filesystem as well as start stop scripts and meta data about the Unix filesystem permissions when PTXdist creates the root filesystem which is later flashed into the onboard flash of an embedded system it takes the information from the ipkg packets as the source in order to make sure that the image is consistent to what the packages contain Internally PTXdist always uses ipkg packets to store it s target data However the ipkg functionality is not always exposed to the target itself So in order to use packets navigate to 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 to make ipkg work at runtime system The ipkg tool can only be used in images created by ptxdist images It s not fully working within the platform i586 root subdirectory used as NFS root filesystem 6 5 2 Packet Installation A common use case for ipkg packets is to push new software to an already deployed target There must be a communication channel to transfer the packet itself to the embedded system i e by using FTP or a secure connection via SFTP or SSH so it has t
46. b libfoo so pointing to libfoo so 1 1 0 in the same directory call install_link foo libfoo so 1 1 0 usr lib libfoo so Create a symbolic link as usr bin foo pointing to bin bar call install_link foo bin bar usr bin foo 5 2 9 install_archive Usage call install_archive lt package gt lt UID gt lt GID gt lt archive gt lt base path gt Installs archives content into e the project s platform i586 root e the project s plat form i586 root debug e an ipkg opkg packet in the project s platform i586 packages All parameters have fixed meanings lt package gt Name of the IPKG OPKG the macro should work on lt UID gt User ID all files and directory of the archive should use in the target s root filesystem A uses the file s directory s UID in the archive lt GID gt Group ID the files and directories should use in the target s root filesystem A uses the file s directory s GID in the archive lt archive gt Name of the archive to be used in this call The given path and filename is used as is lt base path gt Base path component in the root filesystem the archive should be extracted to Can be just for root f Pengutronix 22 5 PTXdist Reference 5 2 10 install_lib Usage call install_lib lt package gt lt UID gt lt GID gt lt permission gt lt libname gt Installs the shared library lt libname gt into the root filesystem e the project s pl
47. be extended by parameters to define the function we want to run If we are unsure what parameter must be given to 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 to the most common parameters to configure and build a PTXdist project menuconfig Starts the Kconfig based project configurator for the current selected userland configuration This menu will give us access to various userland components that the root filesystem of our target should consist of menuconfig platform Starts the Kconfig based platform configurator This menu lets us set up all target specific settings Major parts are e Toolchain architecture and revision e boot loader e root filesystem image type e Linux kernel revision 21 f Pengutronix 3 PTXdist User s Manual Note A PTXdist project can consist of more than one platform configuration at the same time menuconfig kernel Runs the standard Linux kernel Kconfig to configure the kernel for the current selected plat form To run this feature the kernel must be already set up for this platform menuconfig collection If multiple platforms are sharing one userland configuration collection
48. bout your local host and how slow it is With the help of ICECC every host will be a high speed development machine 6 8 Using pre build archives PTXdist is a tool which creates all the required parts of a target s filesystem to breathe life into it And it creates these parts from any kind of source files Ifa PTXdist project consists of many packages the build may take a huge amount of time For internal checks we have a so called ALL YES PTXdist project It has like the name suggests all packages enabled which PTXdist supports To build this ALL YES PTXdist project our build server needs about 6 hours f Pengutronix 19 6 Various Aspects of Daily Work 6 8 1 Introduction While the development of a PTXdist project it is needed to clean and re build everything from time to time to get a re synced project result which honors all changes made in the project But since cleaning and re building everything from time to time is a very good test case if some adaptions are still missing or if everything is complete it can bea real time sink to do so To not lose developer s temper when doing such tests PTXdist can keep archives from the last run which includes all the files the package s build system has installed while the PTXdist s install stage runs for it The next time PTXdist should build a package it can use the results from the last run instead This feature can drastically reduce the time to re build the whole project
49. building blocks in the board setup configuration menu are e Network Network settings for the target e Host Host setup to be able to reach the target system At this point it could be useful to walk to the whole menus and their submenus to get an idea about the amount of features and applications PTXdist currently supports 3 3 2 Adapting Platform Settings Some parts of the OSELAS BSP Pengutronix Generic 2014 07 0 project are platform specific in contrast to the userland configuration that could be shared between platforms We now want to change the used Linux kernel of our current i586 qemu platform It comes with a default linux 3 0 and we want to change it to a more recent linux 3 7 To do so we run ptxdist menuconfig platform In this Kconfig dialogue we navigate to the entry x Linux kernel gt 3 0 kernel version and replace the 3 0 value by the 3 7 value Since PTXdist checks the MDs5 sums of the archives it uses we also must change the MDs sum in the menu entry according to the selected kernel version Use one of the following MD5 sums for a kernel of your choice e 3 7 21223369d682bcf44bcdfe1 521095983 e 3 6 la1760420eac802c541a20ab51a093d1 e 3 5 24153eaaa81dedc9481ada8cd9c3b83d e 3 4 967f72983655e2479f951195953e8480 e 3 3 7133f5a2086a7d7ef97abac610c094f5 3 2 364066fa18767ec0ae5f4e4abcf9dc51 e 3 1 8d43453f8159b2332ad410b19d86a931 e 3 0 398e95866794def22b12dfbc15ce89c0 e 2 6 39 laab7a741abe
50. cal values and as text strings In the case text strings are given PTXdist converts them into the coresponding numerical value based on the BSP local file FIXME projectroot etc 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 5 2 2 touch Usage call touch 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 lt directory path gt Removes the given directory lt directory path gt 5 2 4 install_copy Usage call install_copy lt package gt lt UID gt lt GID gt lt permission gt lt source gt lt dest gt lt strip gt Installs given file or directory into e the project s platform i586 root e the project s platform 1586 root debug f Pengutronix a 5 PTXdist Reference e anipkg opkg packet in the project s platform i586 packages Some of the parameters have fixed meanings lt package gt Name of the IPKG OPKG the macro should work on lt UID gt User ID the file should use in the target s root filesystem lt GID gt Group ID the file should use in the target s root filesystem lt perm
51. can be used based on their pre build archives These kind of packages are always re built Only target related packages can be used based on their pre build archives but there are a few exceptions e Linux kernel It has an incomplete install stage which results into an incomplete pre build archive Due to this it cannot be used as a pre build archive e Barebox bootloader It has an incomplete install stage which results into an incomplete pre build archive Due to this it cannot be used as a pre build archive e some other somehow broken packages all marked with a lt packagename gt _DEVPKG NO in their corre sponding rule file 6 8 5 Workflow with pre build archives We starting with an empty PTXdist project and enabling the pre build archive feature as mentioned in 6 8 2 After that a regular build of the project can be made When the build is finished its time to copy all the pre build archives of interest where the next build will expect them 6 8 3 mentions the step to enable their use It also allows to define a directory The default path of this directory is made from various other menu settings to ensure the pre build archives of the current PTXdist project do not conflict with pre build archives of different PTXdist projects To get an idea what the final path is we can ask PTXdist ptxdist print PTXCONF_PROJECT_DEVPKGDIR home jbe OSELAS BSP Pengutronix OSELAS BSP Pengutronix Generic 2014 07 0 Ifthis directory does n
52. cecc icecream Read their README md for further details Please note as of July 2014 you need at least an ICECC in its version 1 x Older revisions are known to not work 6 7 2 Enabling PTXdist for the Distributed Compiler Since the 2014 07 release PTXdist supports the usage of ICECC by simply enabling a setup switch Run the PTXdist setup and navigate to the new ICECC menu entry ptxdist setup Developer Options gt use icecc usr lib icecc icecc create env icecc create env path Maybe you must adapt the icecc create env path to the setting on your host Most of the time the default path should work 6 7 3 How to use the Distributed Compiler with PTXdist PTXdist still uses two times the count of cores of the local CPU for parallel tasks But if a faster CPU in the net exists ICECC will now start to do all compile tasks on this these faster CPU s instead of the local CPU To really boost the build speed you must increase the tasks to be done in parallel manually Use the ji lt x gt command line option to start more tasks at the same time This command line option just effects one package to build at a time To more increase the build speed use the je lt x gt command line option as well This will build also packages in parallel A complete command line could look like this ptxdist go ji64 je8 This command line will run up to 64 tasks in parallel and builds 8 packages at the same time Never worry again a
53. cked if all necessary programs are installed on the development host The configure script will stop if it discovers that something is missing The PTXdist installation is based on GNU autotools so the first thing to be done now is to configure the packet configure This will check your system for required components PTXdist relies on If all required components are found the output ends with eee checking whether python development files are present yes checking for patch usr bin patch checking whether usr bin patch will work yes configure creating config status config status creating Makefile ptxdist version 2014 07 configured Using usr local for installation prefix Report bugs to ptxdist pengutronix de Without further arguments PTXdist is configured to be installed into usr local which is the standard location for user installed programs To change the installation path to anything non standard we use the prefix ar gument to 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 PTXdist versions can be installed in parallel So if an old version of PTXdist is already installed there is no need to remove it One of the most important tasks for the configure script is to find out if all the programs PTXdist depends on are already present on the development host The sc
54. d idea to modify the generic package rule files installed by PTXdist but it is always possible to copy one of them over into the rules directory of a project Package rule files in the project will precede global rule files with the same name Q My kernel build fails But cannot detect the correct position due to parallel building How can I stop PTXdist to build in parallel A Force PTXdist to stop building in parallel which looks somehow like jbe host gt ptxdist j1 go Q made my own rule file and now get error messages like my_project rules test make 30 unterminated call to function call missing Stop But line 30 only contains call targetinfo and it seems all right What does it mean A Yes this error message is confusing But it usually only means that you should check the following lines for missing backslashes line separators Q I got a message similar to package lt some name gt is empty not generating What does it mean A The ipkg tool was advised to generate a new ipkg packet but the folder was empty Sometime it means a typo in the package name when the install_copy macro was called Ensure all these macros are using the same package name Or did you disable a menuentry and now nothing will be installed Q How do download all required packages at once A Run this command prior the build jbe host gt ptxdist make get This starts to download all required packa
55. e 1990ies people started to develop an alternative to the large commercial operating systems Linux Linux did never start with a ready to use solution people had a problem searched for a solution but didn t find one Then they started to develop one themselves often several people did this f Pengutronix 7 1 Welcome to the Embedded World in parallel and in a huge community based evolution mechanism the best solutions found their way into the Linux kernel which over the time formed one of the most reliable and performant kernels available today This develop and evolute mechanism has shown its effectiveness over and over again in the server and desktop market of today 1 2 From Server to Embedded The fact that for most technical problems that might occur it may be possible to 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 story of Embedded Linux Studies have shown that more than 70 ofthe embedded developers are not satisfied with a black box operating system they want to adapt it to their needs to their special hardware situation which most times is Just Different than anything available Embedded projects are even more variegated than desktop or server projects due to 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 to a kern
56. e do not intend to use a kernel archive we must setup these entries with valid content download Now we can leave the menu and store 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 to the location where PTXdist expects it in the current project In a multi platform project this location is the platform directory usally in configs lt platform directory gt We must store the file with a name selected in the platform setup menu kernel config file 6 1 3 Work Flow Now its up to ourself working on the GIT based kernel source tree and using PTXdist to include the kernel into the root filesystem To configure the kernel source tree we simply run jbe octopus myprj ptxdist kernelconfig To build the kernel jbe octopus myprj ptxdist targetinstall kernel To rebuild the kernel jbe octopus myprj ptxdist drop kernel compile jbe octopus myprj ptxdist targetinstall kernel 6 2 Discovering Runtime Dependencies Often it happens that an application on the target fails to run because one of its dependencies is not fulfilled This section should give some hints on how to discover these dependencies 68 f Pengutronix 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 dyn
57. e for easier dependency handling you should also fill the REQUIRES variable Here you can define from the package management point of view the dependencies of your li brary For example if your library depends on the udev library and requires a specific version of it just add the string udev gt 1 0 0 to the REQUIRES variable Note the listed packages must be comma separated frengutrono 84 Pengutronix 6 Various Aspects of Daily Work CONFLICTS if your library conflicts with a different library add this different library to the CONFLICTS variable from the package management point of view It might be a good idea to include the API version into the names of the library s include file and pkg config file For example in the first API version all files are named like this e usr local lib libfoo 1 s0 0 0 0 e usr local include libfoo 1 h e usr local lib pkgconfig libfoo 1 pc In this case its simple to create the next generation libfoo without conflicting with earlier versions of your library they can co exist side by side e usr local lib libfoo 1 s0 0 0 0 e usr local lib libfoo 2 s0 0 0 0 e usr local include libfoo 1 h e usr local include libfoo 2 h e usr local lib pkgconfig libfoo 1 pc e usr local lib pkgconfig libfoo 2 pc If you want to do so you must rename the header file and the pc file accordingly And adapt the pkgconfig_DATA and include_HEADERS entries in the Makefile am file and the AC_CONFIG_FIL
58. e has been downloaded PTXdist checks the given MD5 sum against the archive content If both sums do not match PTXdist rejects the archive and fails the currently running build e _SUFFIX defines the archive type to make PTXdist choosing the correct extracting tool e _URL defines the full qualified URL into the web for download If alternative download locations are known they can be listed in this variable delimiter character is the space e _DIR points to the directory this package will be build later on by PTXdist e _LICENSE enables the user to geta list of licenses she he is using in her his project licenses of the enabled packages After enabling the menu entry we can start to check the get and extract stages calling them manually one after another Note The shown commands below expect that PTXdist downloads the archives to a global directory named global_src This is not the default setting but we recommend to use a global directory to share all archives between PTXdist based projects Advantage is every download happens only once Refer to the setup command PTXdist provides ptxdist get foo 2009 12 21 10 54 45 http www foo com download src foo 1 1 tar gz Length 291190 284K Lapplication x gzip Saving to global_src foo 1 1 0 tar gz XXXXOGncZA 1 A A A 291 7 190 170K s in 1 75s 2009 12 21 10 54 48 170 KB s global_src foo 1 1 tar gz saved 291190 291190 This command should start
59. e is the most common one PTXdist handles patching automatically After extracting the archive PTXdist checks for the existence of a patch directory with the same name as the package If our package s name is foo 1 1 0 PTXdist searches for patches in 1 project patches foo 1 1 0 2 platform configs i586 qemu patches foo 1 1 0 3 ptxdist lt ptxdist installation path gt patches foo 1 1 0 The patches from the first location found are used Note Due to this search order a PTXdist project can replace global patches from the PTXdist installation This can be useful if a project sticks to a specific PTXdist revision but fixes from a more recent revision of PTXdist should be used 4 2 5 Creating Patches for a Package PTXdist uses the utilities git patch or quilt to 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 directory for the patch series in the local project directory mkdir p patches foo 1 1 0 PTXdist expects a series file in the patch directory and at least one patch Otherwise it fails Due to the fact that we do not have any patch content yet we ll start with a dummy entry in the series file and an empty
60. e the configure script of our foo example refer to section 4 2 1 supports two additional parameters e enable debug Make the program more noisy It s disabled by default e with bar Also build the special executable bar Building this executable is also disabled by default We now want to forward these options to the configure script when it runs in the prepare stage To do so we must again open the rule file with our favourite editor and navigate to the prepare stage entry PTXdist uses the variable FOO_AUTOCONF as the list of parameters to be given to configure Currently this variable is commented out and defined to FOO_AUTOCONF CROSS_AUTOCONF_USR The variable CROSS_AUTOCONF _USR is predefined by PTXdist and contains all basic parameters to instruct configure to prepare for a cross compile environment To use the two additional mentioned configure parameters we comment in this line and supplement this ex pression as follows FOO_AUTOCONF CROSS_AUTOCONF_USR enable debug with bar 41 f Pengutronix 4 PTXdist Developer s Manual Note We recommend to use this format with each parameter on a line of its own This format is easier to 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 J debug with bar Note I
61. el running on nearly every modern 32 bit processor available today x86 PowerPC ARM MIPS m68k cris Super H etc The kernel supplies a hardware abstrac tion 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 story Besides the kernel a Linux based embedded system consists of a userland a filesystem containing all the small tools 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 to use normal Linux distributions like SuSE RedHat Man drake or Debian as a base for their applications things are different for embedded systems Due to the restricted ressources these systems normally have distributions have to 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 today the most customizable 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 to be e auditable and
62. ent PTXdist revisions to projects that are stuck to an older PTXdist 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 to link against host libraries To be sucessful in the embedded world these types of failures must be fixed If required PTXdist provides such fixes per package They are organized in patch series and can be found in the patches directory within a subdirectory using the same name as the package itself PTXdist uses the utility patch or quilt to apply an existing patch series after extracting the archive So every patch series contains a set of patches and one series file to define the order in which the patches must be applied Note Patches can be compressed Besides the patches directory at the main installation location PTXdist searches two additional locations for a patch series for the package in question One location is the project s currently used platform directory If the currently used platform is located in configs i586 qemu PTXdist searches in configs i586 qemu patches lt package name gt If no patch series was found in the platform directory the next location PTXdist it searches for a patch series is the main project directory in patches lt package name gt If both project local locations do not provide a patch series for the specific package PTXdist falls back to the
63. es do not need any processing they are ready to use and must only be present in the build process or at runtime HTML files for example Refer to the section 4 3 for further details on how to use it src make prog This kind of package is built for the target It s 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 developer can use as a starting point for development src cmake prog This kind of package is built for the target It s intended for developments based on the cmake buildsystem Various projects are using cmake instead of make and can be built with this package type PTXdist will prepare it to compile sources in accordance to the target libraries and their settings Creating such a package will also create a simple template project to be used as a starting point for devel opment src qmake prog This kind of package is built for the target It s intended for developments based on the qmake buildsystem If the developer is going to develop a QT based application this rule is prepared to compile sources in accordance to the target libraries and their settings Creating such a package will also create a simple template project to be used as a starting point for development font This package is a helper to add X font files to the root filesystem This package does not create an additional IPKG in
64. es it work 3 1 1 PTXdist s perception of the world o e 31 2 PTXdis s build process a o s so aoma A a we a 32 FirststepswithPTXdISt a co or e eA A a Pe We 3 2 1 Extracting the Board Support Package 1 es 3 2 2 Selecting a Userland Configuration 1 ee 3 2 3 Selecting a Hardware Platform o e e e o 3 2 4 Selectinga Toalchain oe ice a e eee eee e 3 2 5 Building the Root Filesystem Content e e 326 WhatweGotNow s a acor e ca wa cs a E a eee e ee eS 3 2 7 Creating a Root Filesystem Image lt lt ooo 3 2 8 Running all Parts in an emulated Environment QEMU o 3 3 Adapting the OSELAS BSP Pengutronix Generic 2014 07 0 Project o oo 334 Working with Keonfig c soere mesai by rs a a lee a a E 3 3 2 Adapting Platform Settings gt s c coo e a a ee a 3 3 3 Adapting Linux Kernel Settings 2 o e o 3 3 4 Adapting Userland Settings lt lt lt lt oc ee ss 4 PTXdist Developer s Manual 4 1 PTXdist s directory hierarchy Rule Files PatchSeries 4 1 1 4 1 2 f Pengutronix 31 32 32 32 Contents 4 1 3 Runtime Configuration a s o co een ee E 33 4 2 Adding new Packages lt lt c ecco ie ee he ee he ee ee es 33 421 RuleFile Creation ios cms beh sch as a a ew ea hd 34 42
65. f ifdef PTXCONF_FOO_BAR FOO_AUTOCONF with bar else FOO_AUTOCONF without bar endif Please note the trailing PTXCONF_ for each define While Kconfig is using FOO_BAR the rule file must use PTXCONF_FOO_BAR instead It is a good practice to add both settings e g disable debug even if this is the default case Sometimes configure tries to 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 tools if X libraries are found In this case it depends on the build order if the X related tools are built or not All the autocheck features are problematic here So if we do not want configure to guess its settings we must disable everything we do not want Since every optional parameter adds four lines of code to the rule files PTXdist provides some shortcuts to handle it Refer to section 5 2 11 for further details With these special macros in use the file content shown above looks much simpler autoconf FOO_AUTOCONF CROSS_AUTOCONF_USR call ptx endis PTXCONF_FOO_DEBUG debug call ptx wwo PTXCONF_FOO_BAR bar 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 eel call install_copy foo 0 0 0755 FOO_DIR foo usr bin foo ifdef PTXCONF_FOO_BAR call install_copy foo 0 0 07
66. f the released archive name later on You can keep it in sync with the API_LRELEASE but you must not AC_PREFIX_DEFAULT most of the time you can remove this entry because most users expect the default install path prefix is usr local which is always the default if not changed by this macro API_RELEASE defines the API version of your library This API version will be part of the binary library s name later on LT_CURRENT LT_REVISION LT_AGE define the binary compatibility of your library The rules how these numbers are defined are e library code was modified LT_REVISION e interfaces changed added removed LT_CURRENT and LT_REVISION Q e interfaces added LT_AGE e interfaces removed LT_AGE 0 You must manually change these numbers whenever you change the code in your library prior a release CC_CHECK_CFLAGS CC_CHECK_LDFLAGS if you need special command line parameters given to the com piler or linker don t add them unconditionally Always test if the tools can handle the parameter and fail gracefully if not Use CC_CHECK_CFLAGS to check parameters for the compiler and CC_CHECK_LDFLAGS for the linker AX_HARDWARE_FP AX_DETECT_ARMV sometimes it is important to know for which architecture or CPU the current build is for and if it supports hard float or not Please don t try to guess it Ask the compiler instead The M4 AX_HARDWARE_FP and AX_DETECT_ARMV macros will help you REQUIRES to enrich the generated pc fil
67. f this directory does not exist we have to create it and change into it cd mkdir local cd local Next step is to extract the archive tar xjf ptxdist 2014 07 0 tar bz2 If everything goes well we now have a PTXdist 2014 07 0 directory so we can change into it cd ptxdist 2014 07 0 drwxr xr x 10 jb user 248 Sep drwxr xr x 242 jb user 8168 Sep drwxr xr x 2 jb user 1624 Sep drwxr xr x 4 jb user 112 Sep Irwxrwxrwx 1 jb user Oct 15 59 generic 15 59 patches 15 59 platforms 15 59 plugins 20 42 projectroot gt generic ls 1F total 530 rw r r 1 jb user 18446 Sep 9 15 59 COPYING rw r r 1 jb user 4048 Sep 9 15 59 CREDITS rw r r 1 jb user 115540 Sep 9 15 59 ChangeLog Wi PAUSE 57 Sep 9 15 59 INSTALL rw r r 1 jb user 3868 Sep 9 15 59 Makefile in rw r r 1 jb user 4268 Sep 9 15 59 README rw r r 1 jb user 2324 Sep 9 15 59 README devel rw r r 1 jb user 63516 Sep 9 15 59 TODO rwxr xr x 1 jb user 28 Sep 9 15 59 autogen sh drwxr xr x 2 jb user 72 Sep 9 15 59 bin drwxr xr x 12 jb user 352 Sep 9 15 59 config rwxr xr x 1 jb user 224087 Sep 9 17 34 configure rw r r 1 jb user 12196 Sep 9 15 59 configure ac 9 9 9 9 4 11 f Pengutronix 2 Getting a working Environment drwxr xr x 6 jb user 60664 Sep 9 15 59 rules drwxr xr x 9 jb user 936 Sep 9 15 59 scripts drwxr xr x 2 jb user 512 Sep 9 15 59 tests 2 2 3 Prerequisites Before PTXdist can be installed it has to be che
68. for patches for a specific package we can copy the global patch series to our local project directory Now we have the permissions to add more patches or modify the existing ones Also quilt is our friend here to 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 to send these patches to PTXdist mainline 4 2 6 Modifying Autotoolized Packages Autotoolized packages are very picky when automatically generated files get patched The patch order is very important in this case and sometimes it even fails and nowbody knows why To improve a package s autotools based build system PTXdist comes with its own project local autotools to regenerate the autotools 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 autogen sh file in the patch directory 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 libtoolize force copy autoreconf force installiy warnings cross warnings syntax warnin
69. from the runtime system In a second step install the contents of the new ipkg package ipkg list ipkg remove lt package name gt ipkg install lt package name gt ipk 6 6 Increasing Build Speed Modern host systems are providing more than one CPU core To make use of this additionally computing power recent applications should do their work in parallel f Pengutronix 13 6 Various Aspects of Daily Work NEVER RELY JUST ON HOPE ALWAYS DO MORE 6 6 1 Using available CPU Cores PTXdist uses all available CPU cores when building a project by default But there are some exceptions e the prepare stage of all autotools build system based packages can use only one CPU core This is due to the fact the running configure is a shell script e some packages have a broken buildsystem regarding parallel build These kind of packages build success fully only when building on one single CPU core e creating the root filesystem images are also done on a single core only 76 f Pengutronix 6 Various Aspects of Daily Work 6 6 2 Manually adjusting CPU Core usage Manual adjustment of the parallel build behaviour is possible via command line parameters ji lt number gt this defines the number of CPU cores to build a package The default is two times the available CPU cores je lt number gt this defines the number of packages to be build in parallel The default is one package at a time l lt numbe
70. g lt architecture B gt toolchain lt architecture B toolchain path gt go The project contains two individual platforms but they do not share anything else ptxdist select lt project A config gt platformconfig lt architecture A gt toolchain lt architecture A toolchain path gt quiet go amp ptxdist select lt project B config gt platformconfig lt architecture B gt toolchain lt architecture B toolchain path gt go Running one PTXdist in background and one in foreground would render the console output unreadable That is why the background PTXdist uses the quiet parameter in the examples above Its output is still available in the logfile under the platform build directory tree By using more than one virtual console both PTXdists can run with their full output on the console 6 7 Using a Distributed Compiler To increase the build speed of a PTXdist project can be done by doing more tasks in parallel PTXdist itself uses all available CPU cores by default but is is limited to the local host For further speedup a distributed compilation can be used This is the task of ICECC aka icecream With this feature a PTXdist project can make use of all available hosts and their CPUs in a local network 8 f Pengutronix 1 6 Various Aspects of Daily Work 6 7 1 Setting Up the Distributed Compiler How to setup the distributed compiler can be found on the project s homepage at GITHUB https github com i
71. ges in one run It does nothing if the archives are already present in the source path run PTXdist setup first Q I want to backup the source archives my PTXdist project relys on How can find out what packages my project requires to build A First build your PTXdist project completely and then run the following command jbe host gt ptxdist export_src lt archive directory gt It copies all archives from where are your source archives stored to lt archive directory gt which can be your backup media Q To avoid building the OSELAS toolchain on each development host copied it to another machine But on this machine cannot build any BSP with this toolchain correctly All applications on the target are failing to start frengutronix 87 Pengutronix 6 Various Aspects of Daily Work due to missing libraries A This happens when the toolchain was copied without regarding to retain links There are archive programs around that convert links into real files When you are using such programs to create a toolchain archive this toolchain will be broken after extracting it again Solution Use archive programs that retain links as they are tar for example Here an example for a broken toolchain 11 find name libcryptx rwxr xr x 1 mkl ptx 55K 2007 07 25 14 54 lib libcrypt 2 5 sox rwxr xr x 1 mkl ptx 55K 2007 07 25 14 54 lib libcrypt so 1 rw r r 1 mkl ptx 63K 2007 07 25 14 54 usr lib libcrypt a 1
72. gs obsolete warnings unsuppor ted Note In this way not yet autotoolized package can be autotoolized We just have to add the common auto tool template files configure ac and Makefile am for example via a patch series to the package source and the autogen sh to the patch directory 8 f Pengutronix id 4 PTXdist Developer s Manual 4 3 Adding binary only Files Sometimes a few binary files have to be added into the root filesystem Or to be more precise some files that do not need to 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 PTXdist provides more than one way to add such type of data files to the root filesystem it creates The examples in this chapter refer our generic board support package It comes with an example how to add binary only files into PTXdist s build mechanism 4 3 1 Old style single files The old style to add a simple file is present in PTXdist since its early days Just use the install_copy macro in the targetinstall stage in your own customized rules file call install_copy binary_example 0 0 0644 PTXDIST_WORKSPACE local_src binary_example ptx_logo png example ptx_logo png 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 directory local_src bi
73. hing was changed ptxdist goalso will do nothing When PTXdist has finished its job the new bootable kernel can be found at platform i586 images linuximage To boot it again in the QEMU emulation the hard disk image must be re created with ptxdist images configs i586 qemu run The emulated system should now start with a 3 7 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 PTXdist provides Many of them are working out of the box when enabled and executed on the target side Some need additional runtime configura tion but PTXdist comes with most common configurations for such packages In this simple example we want to add the missing head command to our target s shell Assuming we forgot to enable this command we get fPengutronnx 29 Pengutronix 3 PTXdist User s Manual configs i586 qemu 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 to enable is provided by the Busybox package So we navigate to Shell amp Console Tools gt busybox gt Coreutils gt head After activating the head entry we leave the menu and save the new configurat
74. hould help to maintain such projects But some platforms do need special userland think about graphic non graphic platforms To be able to also collect this requirement into 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 to build and ship them A different use case for collections could be the security ofan application While the development is ongoing all kind of debugging and logging helpers are part of the root filesystem But the final production root filesystem uses collections to omit all these helpers and to reduce the risc of security vulnerability PTXdist can handle the following project variations e 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 PTXdist s build process When PTXdist is building one part we call it a package of the whole project it is divided into up to six stages get The package will be obtained from its source downloaded from the web for example extract The package archive get
75. ible to set the file ownership to root This is an important step for reliability so it is highly recommended 2 3 6 Building additional Toolchains The OSELAS Toolchain 2013 12 2 bundle comes with various predefined toolchains Refer the ptxconfigs folder for other definitions To build additional toolchains we only have to clean our current toolchain project removing the current selected_ptxconfig link and creating a new one ptxdist clean rm selected_ptxconfig ptxdist select ptxconfigs any_other_toolchain_def ptxconfig ptxdist go All toolchains will be installed side by side architecture dependent into directory opt OSELAS Toolchain 2013 12 2 architecture_part Different toolchains for the same architecture will be installed side by side version dependent into directory opt OSELAS Toolchain 2013 12 2 architecture_part version_part 18 f Pengutronix 3 PTXdist User s Manual This chapter should give any newbie the information he she needs to be able to handle any embedded Linux projects based on PTXdist Also the advanced user may find new valueable information 3 1 How does it work PTXdist supports various aspects of the daily work to develop deploy and maintain an embedded Linux based project Project Handling Quality Management Development Deployment Toolchains Libraries Automated Automated Debugging Tools Testing Production IDE Eclipse Figure 3 1 Objectives in a pro
76. ing building a Toolchain Pengutronix also provides ready to use toolchains in a binary manner These toolchains are built from the OS ELAS Toolchain bundle so they comply with all of Pengutronix s board support packages and we can use them instead of building our own one The binary OSELAS toolchains are provided as Debian Distribution Packages Also most non Debian distributions can handle such packages In order to install the OSELAS binary toolchains on a Debian based system the following steps are required Add the OSELAS Server as a Package Source To register the OSELAS package server to the list of known package servers we add a new file with the name pengutronix list into the directory etc apt sources list d The basename of this file isn t important while the extension list is The contents of this new file describe the Pengutronix server as an available package source It is defined via one text line deb http debian pengutronix de debian sid main contrib non free Note if the directory etc apt sources list d does not exist the text line mentioned above must be added to the file etc apt sources list instead Make the OSELAS Server Content available The package manager now must update its packages list with the following command apt get update PPengutronix 15 Pengutronix 2 Getting a working Environment Install the Archive Keyring To avoid warnings about untrusted package sources we can
77. ing order e project s directory projectroot i586 etc foo project s directory projectroot etc foo i586 platform s directory configs i586 qemu projectroot etc foo project s directory projectroot etc foo ptxdist s directory generic etc foo e project s directory FOO_DIR etc foo The generic rules are looking like the following e PTXDIST_WORKSPACE projectroot PTXDIST_PLATFORMSUFFIX etc foo e PTXDIST_WORKSPACE projectroot etc foo PTXDIST_PLATFORMSUFFIX e PTXDIST_PLATFORMCONFIGDIR projectroot etc foo e PTXDIST_WORKSPACE projectroot etc foo e PTXDIST_TOPDIR generic etc foo e FOO_DIR etc foo Note You can get the current values for the listed variables above via running PTXdist with the print parameter ptxdist print PTXDIST_PLATFORMSUFFIX 5 2 8 install_link Usage call install_link lt package gt lt point to gt lt where gt Installs a symbolic link into 58 f Pengutronix 5 PTXdist Reference e the project s platform i586 root e the project s platform i586 root debug e anipkg opkg packet in the project s platform i586 packages The parameters and their meanings lt package gt Name of the IPKG OPKG the macro should work on lt point to gt Path and name the link should point to Note This macro rejects absolute paths If needed use relative paths instead lt where gt Path and name of the symbolic link A few usage examples Create a symbolic link as usr li
78. ing written for the embedded system Package updating may be a requirement even during the system s life cycle for example for updating a customer application in the field 72 f Pengutronix 6 Various Aspects of Daily Work Conventional Linux distributions like Debian SuSE or Fedora use package systems like RPM or DEB to 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 e offers installation removement of packages e has no big database but a very low overhead e 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 mean while 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 post rm So even if no ipkg management utilities are available developers can modify the archives with standard shell and console tools 6 5 1 ipkg Usage in PTXdist PTXdist end users and packet developers don t have to care directly about ipkg Packages are being cre
79. install the OSELAS archive keyring with the following command apt get install pengutronix archive keyring Install the binary OSELAS Toolchain Now everything is in place to install the binary OSELAS toolchain for the OSELAS BSP Pengutronix Generic 2014 07 0 board support package apt get install oselas toolchain 2013 12 2 1586 unknown 1inux gnu gcc 4 8 2 glibc 2 18 binutils 2 24 kernel 3 12 sanitized These package names are very long and hard to type without making typos An easier way is to ask the package manager for available toolchains and just use the name by copy and paste it apt cache search oselas toolchain i586 unknown oselas toolchain 2013 12 2 i1586 unknown linux gnu gec 4 8 2 glibc 2 18 binutils 2 24 kernel 3 12 sanitized The binary OSELAS Toolchain Package for non Debian Distributions The Debian Distribution Packages can be found on our server at http debian pengutronix de debian pool main o The OSELAS BSP Pengutronix Generic 2014 07 0 related OSELAS toolchain package can be found here Subpath is oselas toolchain 2013 12 2 1586 unknown 1inux gnu gcc 4 8 2 glibc 2 18 binutils 2 24 kernel 3 12 sanitized Package filename is oselas toolchain 2013 12 2 1586 unknown 1inux gnu gcc 4 8 2 glibc 2 18 binutils 2 24 kernel 3 12 sanitizedx deb Package filenames for 32 bit host machines are ending on _i386 deb and for 64 bit host machines on x_amd64 deb 2 3 3 Building a Toolchain P
80. ion Once again a ptxdist go will build or re build the busybox package due to its configuration change And also once again after finishing its job the following commands let us test the new command ptxdist images configs i586 qemu 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 00 debugfs sys kernel debug debugfs defaults noauto 00 devpts dev pts devpts defaults 00 none tmp tmpfs defaults mode 1777 uid 0 gid 0 0 0 none sys sysfs defaults 00 We are done now These simple examples should give the users a quick feeling how things are working in PTXdist and how to modify them Adapting this generic BSP to a different platform with nearly the same features as our reference platforms is possible with this knowledge But most ofthe time a user needs more detailed adaptions to be able to fit all requirements ofthe new platform At this point oftime we are no longer ordinary users of PTXdist we become developers now So right now it s time to read the PTXdist Developer s Manual o f Pengutronix 4 PTXdist Developer s Manual This chapter shows all or most of the details of how PTXdist works I HAVE A NEW COFFEE MACHINE IT S PROGRAMMABLE o x a os x o o o TURING COMPLETE SOME GEEKS ARE SPOILSPORTS 31 f Pengutro
81. ission gt Permission in an octal value the file should use in the target s root filesystem The remaining parameters vary with the use case The lt source gt parameter can be e a directory path that should be created in the target s root filesystem In this case the lt destination gt must be omitted The given path must always start with a and means the root of the target s filesystem e an absolute path to a file that should be copied to the target s root filesystem To avoid fixed paths all packages are providing the lt package gt _DIR variable So this parameter in our foo example package can be a FOO_DIR foo e a minus sign PTXdist uses the lt destination gt parameter in this case to locate the file to copy from This only works if the package uses the default install stage Only in this case an additional folder in platform i586 packages will be created for the package and its files For our foo example package this directory is platform 1586 packages foo 1 1 0 The lt dest gt parameter can be e omitted if a directory in target s root filesystem should be created For this case the directory to be created is in the lt source gt parameter e an absolute path and filename with its root in target s root filesysem It must start with a slash If also the lt source gt parameter was given the file can be renamed while copying If the lt source gt parameter was given as a minus sign the lt destination gt
82. ist_installed busybox 1 1 3 figlet 222 celliilys 4 gdbserver 6 4 callo 27816 alle 2 5 ipkg 0 99 163 ixp firmware 1 kernel modules 2 6 18 libxml2 2 6 27 me 476 1 memedit 0 7 ne rses Ob Ole permes 22 1 pureftpd 1 0 21 readline 5 0 reaus ILo strace 4 5 14 20061101 udev 088 zilio 12s 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 f Pengutronix e 6 Various Aspects of Daily Work Adding a Package Adding a new packet or replacing an already installed one is done by ipkg install lt package name gt ipk Note the trailing ipk This extension must be given if the package file is already part of the filesystem Otherwise ipkg tries to 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 ipkg list and remove it s contents from the runtime system with ipkg remove lt package name gt Upgrading a Package To upgrade a package first remove it s current contents
83. ives support o e ee 81 6 8 5 Workflow with pre build archives o e e 81 0 8 0 USESCASES auna a A ate Ba IE a OA ed 82 6 9 Downloading Packages from the Web o a 82 6 10 Creating a new Autotools Based Library o ee 82 6 10 1 Creating the Library Template e a 83 6 10 2 Licence related stuff o e e 83 6 10 3 Build system related files o o e emo 84 6 10 4 Template file for pkg config lt lt lt lt oo 85 6 10 5 Generic template files o o e 86 6 10 6 Library related files o o e e 86 6 11 Frequently Asked Questions FAQ 2 o e 87 7 Document Revisions go 8 Thanks 91 9 Getting help 92 Odi Wailing Lists oo ee a eee ac ae a ce we ee a bd a e a te a ae 92 9 1 1 AboutPTXdistin Particular 2 oe a s ae e a ee 92 5 f Pengutronix Contents 9 1 2 About Embedded Linux in General o e ee 92 9 2 About Working on the Linux Kernel o e ee 92 93 UNQUIRE si aae aa Perea as a Pee A 92 9 4 Commercial Support o occ cee eee ee ed a li we oh 93 6 f Pengutronix 1 Welcome to 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 to start
84. ix Generic 2014 07 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 to select one of the possible platforms to build for In this case we want to build for the Generic i586 ptxdist platform configs i586 qemu platformconfig info selected platformconfig configs i586 qemu platformconfig Note Ifyou have installed the OSELAS Toolchain at its default location PTXdist should already have detected the proper toolchain while selecting the platform In this case it will output found and using toolchain gt opt OSELAS Toolchain 2013 12 2 1586 unknown 1inux gnu gcc 4 8 2 glibc 2 18 binutils 2 24 kernel 3 12 sanitized bin Ifitfails you can continue to select the toolchain manually as mentioned in the next section Ifthis autodetection was successful we can omit the steps of the section and continue to build the BSP PPengutronix 23 Pengutronix 3 PTXdist User s Manual 3 2 4 Selecting a Toolchain If not automatically detected the last step in selecting various configurations is to select the toolchain to be used to build everything for the target ptxdist toolchain opt OSELAS Toolchain 2013 12 2 1586 unknown linux gnu gcc 4 8 2 glibc 2 18 binutils 2 24 kernel 3 12 sanitized bin 3 2 5 Building the Root Filesystem Content
85. ject The most important part is the development For this project phase PTXdist provides features to ensure repro ducibility and verifiability 3 1 1 PTXdist s perception of the world PTXdist works project centric A PTXdist project contains all information and files to populate any kind of target system with all required software components e Specific configuration for Bootloader Kernel Userland root filesystem e Adapted files or generic ones for runtime configuration e Patches for all kind of components to fix bugs or improve features PPengutronix 19 Pengutronix 3 PTXdist User s Manual Some of these information or files are coming from the PTXdist base installation patches for example but also can be part of the project itself By this way PTXdist can be adapted to any kind of requirement Most users are fine with the information and files the PTXdist base installation provides Development of PTXdist is done in a way to find default settings most user can work with But advanced users can still adaptto their special needs As stated above a PTXdist project consists of all required parts some of these parts are separated by design PTXdist 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 into one single project s
86. ject it is working on These settings belong to users preferences or simply some network settings to permit PTXdist to download required packages boardsetup PTXdist based projects can provide information to setup and configure the target automatically 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 lt from gt lt to gt this action clones an existing project from the projects list into a new directory The lt from gt argument must be a name gotten from ptxdist projects command the lt to gt argument is the new project and directory name created in the current directory menuconfig start the menu to configure the project s root filesystem This is in respect to user land only Its the main menu to select applications and libraries the root filesystem of the target should consist of menuconfig platform this action starts the menu to configure platform s settings As these are architecture and target specific settings it configures the toolchain the kernel and a bootloader but no user land components Due to a project can support more than one platform this will configure the currently selected platform The short form for this action is platformconfig menuconfig kernel start the menu to configure the platform s kernel As
87. l stages are working as expected and to select the required parts to get them installed in the target root filesystem Also we must find a reasonable location where to add our new menu entry to configure the package The generated skeleton starts to add the new menu entry in the main configure menu if we left the section name unchanged Running ptxdist menuconfig will show it on top of all other menus entries To be able to implement and test all the other required steps for adding a new package we first must enable the package for building Fine tuning the menu can happen later on The rule file skeleton still lacks some important information Let s take a look into some of the top lines of the generated rule file rules foo make FOO_VERSION 1 1 0 FOO_MD5 FOO foo FOO_VERSION f Pengutronix 4 PTXdist Developer s Manual FOO_SUFFIX tar gz FOO_URL http www foo com download src FOO FOO_SUFFIX FOO_SOURCE SRCDIR FOO FOO_SUFFIX FOO_DIR BUILDDIR FOO FOO_LICENSE unknown We can find these lines with different content in most or all of the other rule files PTXdist comes with Up to the underline character is always the package name and after the underline character is always PTXdist specific What does it mean e _ VERSION brings in the version number of the release and is used for the download and IPKG OPKG package generation e _MDs to be sure the correct packag
88. lation rules directory to get an idea what section names are available 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 f Pengutronix 40 4 PTXdist Developer s Manual apache2_mod_python in SECTION networking ES klibc module init tools 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 hosttools_noprompt libssh2 in SECTION networking Porting a new package to PTXdist 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 to 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 to 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 to enable or disable features or to configure them in a specific way We assum
89. m this issue The only solution is to avoid whitespaces in paths and filenames fPengutronn 89 Pengutronix 7 Document Revisions 2010 01 08 2010 01 11 2010 01 11 2010 01 20 2010 01 21 2010 04 15 2010 04 16 2010 05 20 2010 05 20 2010 05 20 2011 01 27 2011 01 27 2011 01 27 2011 01 27 2011 10 21 2011 11 16 2012 04 04 2012 04 05 2013 11 13 2013 12 09 2013 12 12 2014 01 10 2014 06 19 2014 07 07 2014 07 07 Initial Revision Section Adding simple Files to the Build Process added Section Variables reference added Section Debugging with CPU emulation added Section PTXdist parameter reference added Section Adding new Packages extended Section Using Existing Toolchains extended Section Adding binary only Files added Section Adding Files into the Build foldet into Adding binary only Files Section Adapting Userland Settings extended Section Rule File Macro Reference install_tree documentation added Section Rule File Macro Reference install_alternative search order fixed Section Variables Reference some more useful variables added Section Adding new Packages documentation adapted to current ptxdist behaviour Section Adding new Packages documentation adapted to current ptxdist behaviour Section Using an External Kernel Source Tree documentation adapted to current ptxdist behaviour Section Rule File Macro Reference add more common macros Secti
90. mkl ptx 64K 2007 07 25 14 54 usr lib libcrypt_p a 1 mkl ptx 55K 2007 07 25 14 54 usr lib libcrypt sox Wai TPWXP XP X And in contrast this one is intact 11 find name libcryptx rwxr xr X 1 mkl ptx 55K 2007 11 03 13 30 lib libcrypt 2 5 sox Irwxrwxrwx 1 mkl ptx 15 2008 02 20 14 52 lib libcrypt so 1 gt libcrypt 2 5 sox rw r r 1 mkl ptx 63K 2007 11 03 13 30 usr lib libcrypt a 1 mkl ptx 64K 2007 11 03 13 30 usr lib libcrypt_p a 1 mkl ptx 23 2008 02 20 14 52 usr lib libcrypt so gt lib libcrypt so 1 Tw lrwxrwxrwx Q I followed the instructions how to integrate my own plain source project into PTXdist But when try to build it get extract archive path to my sources extract dest path to my project build target Unknown format cannot extract But the path exists A PTXdist interprets a file two slashes in the URL as a project related relative path So it searches only in the current project for the given path Only file three slashes will force PTXdist to use the path as an absolute one This means file bla blub will be used as bla blub and file friesel frasel as friesel frasel Q want to use more than one kernel revision in my BSP How can avoid maintaining one ptxconfig per kernel A One solution could be to include the kernel revision into the name of the kernel config file Instead of the de fault kernelconfig target name you should use kernelconfig lt
91. mmon cases But if our project requires a special setup we can just copy the default one to the local projectroot etc fstab modify it and we are done The next time PTXdist builds the root filesystem it will use the local fstab instead of the global default one 4 2 Adding new Packages PTXdist 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 to integrate new packages into the project At first a summary about possible application types which PTXdist can handle e host type This kind of package is built to run on the build host Most of the time such a package is needed if another target relevant package needs to generate some data For example the glib package depends on its own to 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 to provide these utilities runnable on the build host It sounds strange to 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 e klibc type This kind of package is built against klibc to be part of an initramf
92. n our example platform 1586 packages foo 1 0 0 here 5 2 11 ptx endis To convert the state set unset of a variable into an enable disable string use the ptx endis macro Ifthe given lt variable gt is set this macro expands to the string enable if unset to disable instead Usage call ptx endis lt variable gt lt parameter gt An example 60 f Pengutronix 5 PTXdist Reference FOO_CONF_OPT call ptx endis FOO_VARIABLE something Depending on the state of FOO_VARIABLE this line results into FOO_CONF_OPT enable something if FOO_VARIABLE is set FOO_CONF_OPT disable something if FOO_VARIABLE is unset Refer ptx disen for the opposite string expansion 5 2 12 ptx disen To convert the state set unset of a variable into a disable enable string use the ptx disen macro If the given lt variable gt is set this macro expands to the string disable if unset to enable instead Usage call ptx disen lt variable gt lt parameter gt An example FOO_CONF_OPT call ptx disen FOO_VARIABLE something Depending on the state of FOO_VARIABLE this line results into FOO_CONF_OPT disable something if FOO_VARIABLE is set FOO_CONF_OPT enable something if FOO_VARIABLE is unset Refer ptx endis for the opposite string expansion 5 2 13 ptx wwo To convert the state set unset of a variable into a with without string use the ptx wwo macro If the given lt vari able gt
93. nary_example to 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 to install more than one file we need one call to the install_copy macro per file This is even harder if not only a set of files is to be installed but a whole directory tree with files instead 4 3 2 New style using archives If a whole tree of files is to 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 to be installed in a correct manner e the file itself and its name e the directory structure and the final location of every file in this structure e 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 directory local_src archive_example to target s root filesystem Refer 5 2 9 for further information about using the install_archive macro Using an archive can be usefull to install parts of the root filesystem that are not covered by any open source license Its possible to ship the binaries within the regular BSP without the need for their sources However it is possible for the customer to re create everything
94. nce 5 3 2 Skipping a Stage For the case that a specific stage should be skipped an empty rule must be provided STATEDIR package lt stage_to_skip gt call targetinfo call touch Replace the lt stage_to_skip gt by get extract prepare compile install or targetinstall 5 4 PTXdist parameter reference PTXdist is a command line tool which is basicly called as ptxdist lt action args gt options 5 4 1 Setup and Project Actions menu this will start a menu front end to control some of PTXdist 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 lt config gt this action will select a user land configuration This step is only required in projects where no selected_ptxconfig file is present The lt config gt argument must point to a valid user land configuration file PTXdist provides this feature to enable the user to maintain more than one user land configuration in the same project platform lt config gt this action will select a platform configuration This step is only required in projects where no selected_platform file is present The lt config gt argument must point to a valid platform configuration file PTXdist provides this feature to enable the user to maintain more than one platform in one project setup PTXdist uses some global settings independent from the pro
95. nd platform This can reduce the required time to build the second platform from hours to minutes 6 9 Downloading Packages from the Web Sometimes it makes sense to get all required source archives at once For example prior to a shipment we want to also include all source archives to free the user from downloading it by him herself PTXdist supports this requirement by the export_src parameter It collects all required source archives into one given single directory To do so the current project must be set up correctly e g the select and platform com mands must be ran prior the export_src step Ifeverything is set up correctly we can run the following commands to get the full list of required archives to build the project again without an internet connection mkdir my_archives ptxdist export_src my_archives PTXdist will now collect all source archives to the my_archives directory Note If PTXdist is configured to share one source archive directory for all projects this step will simply copy the source archives from the shared source archive directory Otherwise PTXdist will start to download them from the world wide web 6 10 Creating a new Autotools Based Library Developing your own library can be one of the required tasks to support an embedded system PTXdist comes with an autotoolized library template which can be simply integrated into a PTXdist project 82 f Pengutronix 6 Various Aspects of Daily Work 6 10
96. nd will run the application usr bin myapp built for an i586 CPU on the build host and is using all library compontents from the current directory 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 PTXdist 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 i586 root debug platform 1586 root debug qemu i386 g 1234 cpu i586 L usr bin myapp Note PTXdist always builds two root filesystems platform i586 root and platform i586 root debug platform i586 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 i586 root debug still containing the debug symbols and are much bigger in size The added g 1234 parameter lets QEMU wait for a GDB connection to run the application In the second console we start GDB with the correct architecture support This GDB c
97. nfig 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 bottom part of our visual screen To enter one of the menus we navigate to this entry to 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 to entera menu we also can press alt s and to 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 toggle the selection Or to be more precise and faster we use the key y to select an entry and key n to deselect it To get help for a specific menu topic we navigate vertically to highlight it and horizontally to select the Help entry Then we can press Enter to 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 Meaning of visual feedbacks in Kconfig e Submenus to enter are marked with a trailing gt Note Some submenus are also marked with a leading bracket To enter them we first must select en able them x Entries with a list of selectable alternatives are also marked with a trailing gt 26 f Pengutronix 3 PTXdist User s Manual Figure 3 3 Main userland configuration menu
98. nix 4 PTXdist Developer s Manual e where are the files stored that PTXdist uses when building packages e how patching works e where is PTXdist fetching a package s runtime configuration files from e how to control a package s build stages e how to add new packages 4 1 PTXdist s directory hierarchy Note Referenced directories are meant relative to the PTXdist main installation location if not otherwise stated If not configured differently this main path is usr local 1ib ptxdist 2014 07 0 4 1 1 Rule Files When building a single package PTXdist needs the information on how to handle the package i e on howto get itfrom the source up to what the target needs at runtime This information is provided by a rule file per package PTXdist collects all rule files in its rules directory Whenever PTXdist builds something all these rule files are scanned at once These rule files are global rule files valid for all projects PTXdist uses a mechanism to be able to add or replace specific rule files on a per project base If a rules directory exists in the current project its content is scanned too These project local rule files are used in addition to 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 to extend or adapt packages for specific project requirements Or it can be used for bug fixing by backporting rule files from more rec
99. nning ptxdist print PATH ifthe output still contains any kind of current directory as a component If yes remove it first tar xf OSELAS Toolchain 2013 12 2 tar bz2 cd OSELAS Toolchain 2013 12 2 ptxdist select ptxconfigs 4 1586 unknown linux gnu_gec 4 8 2_glibc 2 18_binutils 2 24 kernel 3 12 sanitized ptxconfig ptxdist go frengutrono 17 Pengutronix 2 Getting a working Environment At this stage we have to go to our boss and tell him that it s probably time to go home for the day Even on reasonably fast machines the time to build an OSELAS Toolchain is something like around 30 minutes up to a few hours Measured times on different machines e Single Pentium 2 5 GHz 2 GiB RAM about 2 hours e 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 e 24 Xeon cores 2 54 GHz 96 GiB RAM about 22 minutes Another possibility is to read the next chapters of this manual to find out how to start a new project When the OSELAS Toolchain project build is finished PTXdist is ready for prime time and we can continue with our first project 2 3 5 Protecting the Toolchain All toolchain components are built with regular user permissions In order to avoid accidential changes in the toolchain the files should be set to read only permissions after the installation has finished successfully It is also poss
100. ntains a mechanism to automatically apply patches to packages The patches are bundled into a separate archive Nevertheless they are nec essary to build a working system Package Descriptions For each software component there is a recipe file specifying which actions have to be done to prepare and compile the software Additionally packages contain their configuration sniplet for the config system 10 f Pengutronix 2 Getting a working Environment Toolchains PTXdist does not come with a pre built binary toolchain Nevertheless PTXdist itself is able to build toolchains 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 toolchain 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 Do the following steps at best in your own home directory HOME You need root permissions only in the make install step and nowhere else To install PTXdist the archive Pengutronix provides has to be extracted ptxdist 2014 07 0 tar bz2 The PTXdist software itself The PTXdist archive has to be extracted into some temporary directory in order to be built before the installation for example the local directory in the user s home I
101. o 0 0 home jbe foo usr share bar Install all files from the tree found in the current package FOO to the root filesystem at location usr share bar call install_tree foo 0 0 usr share bar If the current package is foo 1 0 the base path for the directory tree will be PKGDIR foo 1 0 usr share bar 6 f Pengutronix i 5 PTXdist Reference 5 2 6 install_alternative_tree Usage call install_alternative_tree lt package gt lt UID gt lt GID gt lt destination dir gt Installs the whole source directory tree with all files from the given directory into e the project s platform i586 root e the project s platform i586 root debug e an ipkg packet in the project s platform i586 packages The lt destination dir gt is used like in the install_alternative to let PTXdist search in the same directories and order for the given directory Some of the parameters have fixed meanings lt package gt Name of the IPKG OPKG the macro should work on lt UID gt User ID the directories and files should use in the target s root filesystem or to keep the UID from the source lt GID gt Group ID the directories and files should use in the target s root filesystem or to keep the GID from the source lt destination dir gt The basename of the to be installed tree in the root filesystem Note This installation macro e uses the same permission flags in the destination dir as found in the source di
102. o 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 to store the packet itself A good rule of thumb is to have twice the size of the installed package while the packet is being installed the archive as well as it s contents must fit into the system storage This may be a problem on space constrained systems If the packet was transferred it is necessary to have remote shell access to the box either via telnet or if security is an issue by using SSH It is also possible to automate this process by using an intelligent update mechanism The shell is being used to start the necessary commands If the packet was installed the ipkg archive can be removed again f Pengutronix n 6 Various Aspects of Daily Work 6 5 3 Automatic Packet Download It is also possible to let the embedded system download ipkg packets automatically from a network source with out pushing the packets from the outside In order to do so a valid URL must be written into the etc ipkg conf file In this case one of the wget implementations in PTXdist must be selected either the one in busybox Shell amp Console Tools BusyBox Networking Utilities or the native implementation Networking Tools 6 5 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 ipkg l
103. o make PTXdist use of this kernel source tree instead of an archive we can simply create a link now jbe octopus cd myprj jbe octopus myprj mkdir local_src jbe octopus myprj ln s linux local_src kernel i586 PTXdist will handle it in the same way as a kernel part of the project Due to this we must setup Some kind of kernel version e Kernel configuration e Image type used on our target architecture e Ifwe want to build modules Patches to be used or not Lets setup these topics We just add the kernel component to it jbe octopus myprj ptxdist platformconfig We must enable the Linux kernel entry first to enable kernel building as part of the project After enabling this entry we must enter it and 6 f Pengutronix l 6 Various Aspects of Daily Work e Setting up the kernel version e Setting up the MD5 sum of the corresponding archive e Selecting the correct image type in the entry Image Type e Configuring the kernel within the menu entry patching amp configuration If no patches should be used on top of the selected kernel source tree we keep the patch series file entry empty As GIT should help us to 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 into the kernel config file entry else PTXdist will fail Also the archive must be present on the host else PTXdist will start a f Even if w
104. omes with the same OSE LAS Toolchain that was also used to build the project In our example we are using the i586 unknown linux gnu toolchain for our qemu i386 CPU 1586 unknown linux gnu gdbtui root debug usr bin myapp This will run a curses based GDB Not so easy to handle we must enter all the commands and cannot click with a mouse but very fast to take a quick look at our application At first we tell GDB where to look for debug symbols The correct directory here is platform i586 root debug gdb set solib absolute prefix platform i586 root debug Next we connect this GDB to the waiting QEMU 71 f Pengutronix 6 Various Aspects of Daily Work gdb target remote localhost 1234 Remote debugging using localhost 1234 New Thread 1 0x40096a7c in _start from root debug lib 1d so 1 As our application is already started we can t use the GDB command start to 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 top part of the running gdbtui console will always show us the current source line Due to the root debug directory 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 impo
105. on Rule file layout documentation adapted to current ptxdist behaviour Section Rule File Macro Reference documentation adapted to current ptxdist behaviour Section Increasing Build Speed added Comics of geek amp poke added all over the place Enjoy Section Using pre build archives added Section Creating a new Autotools Based Library added Section Using a Distributed Compiler added Section Frequently Asked Questions FAQ added x f Pengutronix 9 8 Thanks Usage of the geek amp poke comics with kindly permission of Oliver Widder http geek and poke com PLEASE PLEASE PLEASE PLEASE v x 8 x v o D GIT BLAME The geek amp poke comics are published under the Creative Commonse License CC BY 3 0 http creativecommons org licenses by 3 0 deed en_US 91 f Pengutronix 9 Getting help Below is a list of locations where you can get help in case of trouble For questions how to do something special with PTXdist or general questions about Linux in the embedded world try these 9 1 Mailing Lists 9 1 1 About PTXdist in Particular This is an English language public mailing list for questions about PTXdist See http www pengutronix de mailinglists index_en html on how to subscribe to this list If you want to search through the mailing list archive visit http www mail archive com and search for the list ptxdist Please note again that this m
106. on other Resources o a 69 6 3 Debugging with CPU emulation os usos e a ee a 70 6 3 1 Running an Application made for a different Architecture o 71 6 3 2 Debugging an Application made fora different Architecture 71 6 4 Migration between Releases o e 72 6 5 Software Installation and Upgrade o 72 651 Ipkg Usage i PTMGISE s ce sot a wk a ee RE Sle A A ie E te 73 652 Packet Installation cos Ga he a SO i ed ee pd 73 6 5 3 Automatic Packet Download lt e ss aas ee ee ee ee ks 74 654 Theipke Command o o corect i iui ee me a ew a Pe A 74 6 6 Increasing Build Speed o eo osc soi ama aa ee ee a ee G 75 6 6 1 Using available CPU Cores o 76 6 6 2 Manually adjusting CPU Core usage o o noonoo a 77 6 6 3 Building in Background lt 225 ceeds u ppa o a a ees 77 6 6 4 Building Platforms in Parallel oa aaa a 77 6 7 Using a Distributed Compiler aaao ee 78 6 7 1 Setting Up the Distributed Compiler aaoo a 79 6 7 2 Enabling PTXdist for the Distributed Compiler 79 6 7 3 How to use the Distributed Compiler with PTXdist o 79 6 8 Using pre build archives lt lt a a coooa ee ee 79 6 81 Introduction a 6 fe ak a a Oe a a E e a i a 80 6 8 2 Creating pre build archives e 80 6 8 3 Using pre build archives o oo e e 80 6 8 4 Packages without pre build arch
107. ot exist we can simply create it mkdir p home jbe OSELAS BSP Pengutronix OSELAS BSP Pengutronix Generic 2014 07 0 81 j Pengutronix 6 Various Aspects of Daily Work Now its time to copy the pre build archives to this new directory We could simply copy all pre build archives from the platform i586 packages directory But we should keep in mind if any of the related packages are under development we must omit its corresponding pre build archives in this step cp platform 1586 packages dev tar gz home jbe OSELAS BSP Pengutronix OSELAS BSP Pengutronix Generic 2014 07 0 6 8 6 Uses cases Some major possible use cases are covered in this section e Speed up a re build of one single project e Sharing pre build archives between two platforms based on the same architecture To simply speed up a re build of the whole project without development on any of the used packages we just can copy all dev tar gz archives after the first build to the location where PTXdist expects them at the next build time If two platforms are sharing the same architecture it is possible to share pre build archives as well The best way it can work is if both platforms are part of the same PTXdist project They must also share the same toolchain settings patch series and rule files If these precautions are handled the whole project can be built for the first platform and these pre build archives can be used to build the project for the seco
108. patch file touch patches foo 1 1 dummy echo dummy gt patches foo 1 1 0 series Next is to 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 directory pointing to our local patch directory Working this way will ensure that we do not lose our created patches if we enter ptxdist clean foo by 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 f Pengutronix a 4 PTXdist Developer s Manual All we have to do now is to do the modification we need to make the package work We change into the build directory and use quilt to create new patches add files to respective patches modify these files and refresh the patches to save our changes We recommend this way when modifying source files But this way is improper when an autotools based buildsys tem itself needs modifications Referto section 4 2 6 on how PTXdist can handle this special task Adding more Patches to a Package If we want to add more patches to an already patched package we can use nearly the same way as creating patches for the first time But ifthe patch series comes from the PTXdist main installation we do not have write permissions to these directories do NEVER work on the main installation directories NEVER NEVER NEVER Due to the search order in which PTXdist searches
109. pular 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 in creasingly often replaced by modern plug and play aware communication channels USB FireWire IEEE1394 Ethernet amp friends are more and more directly being integrated into today s microcontroller hardware Whereas some of these interfaces can somehow be handled the old controller style way of writing software the devel oper following this way will not be able to 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 to support all the different in terfaces communication stacks development tools 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 today 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 th
110. r This is valid for directories and regular files e skips all directories with names like svn git pc and CVS in the source directory Examples Install the whole tree found in project s projectroot usr share bar to the root filesystem at location usr share bar call install_alternative_tree foo 0 0 usr share bar 5 2 7 install_alternative Usage call install_alternative lt package gt lt UID gt lt GID gt lt permission gt lt destination gt Installs given files or directories into e the project s platform i586 root e the project s plat form i586 root debug e an ipkg opkg packet in the project s platform i586 packages The base parameters and their meanings f Pengutronix ci 5 PTXdist Reference lt package gt Name of the IPKG OPKG the macro should work on lt UID gt User ID the file should use in the target s root filesystem lt GID gt Group ID the file should use in the target s root filesystem lt permission gt Permission in an octal value the file should use in the target s root filesystem The parameter lt destination gt is meant as an absolute path and filename in target s root filesystem PTXdist searches for the source of this file in e the local project e inthe used platform e PTXdist s install path e inthe current package As this search algorithm is complex here an example for the file etc foo in package FOO PTXdist will search for this file in the follow
111. r gt limit the system load to the given value A Building packages in parallel is still not tested very well and migh fail 6 6 3 Building in Background To build a project in background PTXdist can be niced n lt number gt run PTXdist and all of its child processes with the given nicelevel lt number gt Without a nicelevel the default is 10 6 6 4 Building Platforms in Parallel Due to the fact that more than one platform can exist in a PTXdist project all these platforms can be built in parallel within the same project directory As they store their results into different platform subdirectories they will not conflict Only PTXdist must be called differently because each call must be parametrized individually The used Platform Configuration ptxdist platform lt some platform config gt This call will create the soft link selected_platformconfig to the lt some platform config gt in the project s direc tory After this call PTXdist uses this soft link as the default platform to build for It can be overwritten temporarily by the command line parameter platformconfig lt different platform config gt The used Project Configuration ptxdist select lt some project config gt This call will create the soft link selected_ptxconfig to the lt some project config gt in the project s directory After this call PTXdist uses this soft link as the default configuration to build the project It can be overwrit
112. required from the BSP to get their target up and running again Another use case for the archive method could be the support for different development teams One team pro vides a software component in the archive format the other team does not need to build it but can use it in the same way than every other software component f Pengutronix i 4 PTXdist Developer s Manual 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 PTXdist create them for us ptxdist newpackage file ptxdist creating a new file package ptxdist enter package name my_binfiles ptxdist enter version number s il ptxdist enter package author Juergen Borleis lt jbe pengutronix de gt 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 Both files now must be customized to meet our requirements Due to the answer rootfs to the enter package section question we will find the new menu entry in Root Filesystem gt lt gt my_binfiles NEW Enabling this new entry will also run our stages in rules my_binfiles make the next time we enter ptxdist go 50 f Pengutronix 5 PTXdist Reference f Pengutronix WHAT DO YOU THINK SHOULD I DELETE THIS DOCUMENT OR PUT IT INTO OUR PROJECT FOLDER a 0d Y
113. res foo and bar and its configure provides switches to 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 f Pengutronix an 4 PTXdist Developer s Manual 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 config FOO_FOO bool prompt build foo config FOO_BAR bool prompt build bar endif main menu entry of the package to ensure that the calculation of the dependencies between the Do not add these select statements to the correspondig menu entry They must belong to the A packages is done in a correct manner Managing External Runtime Dependencies Some packages are building all of their components and also installing them into the target s sysroot But only their targetinstall stage decides which parts are copied to 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 to the math library 1ibm Our new package was built successfully because the linker was able to link our binaries ag
114. rgetinfo cd package _DIR amp amp package _PATH package _MAKE_ENV MAKE package _MAKE_OPT package _MAKE_PAR call touch If the package _MAKE_ENV is not defined it defaults to CROSS_ENV If some additional variables should be added to the package _MAKE_ENV always begin with the CROSS_ENV and then add the additional variables If the package _MAKE_OPT is intended for additional parameters to be forwarded to make or to overwrite some settings from the package _MAKE_ENV If not defined in the rule file it defaults to an empty string Note package _MAKE_PAR can be defined to YES or NO to control if the package can be built in parallel install Stage Default Rule If the install stage is omitted PTXdist runs instead STATEDIR package install call targetinfo cd package _DIR amp amp package _PATH package _MAKE_ENV MAKE package _INSTALL_OPT call touch Note package _INSTALL_OPT is always defined to 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 PTXdist has no idea what is required on the target at run time This stage is up to the developer only Refer to section 5 2 for further info on how to select files to be included in the target s root filesystem frengutronux 64 Pengutronix 5 PTXdist Refere
115. ript will stop with an error message in case something is missing Ifthis happens the missing tools have to 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 PTXdist into it s final location In order to write to usr local this step has to be performed as user root sudo make install enter password bel If we don t have root access to the machine it is also possible to install PTXdist into some other directory with the prefix option We need to take care that the bin directory below the new installation dir is added to our PATH environment variable for example by exporting it in bashrc 12 f Pengutronix 2 Getting a working Environment The installation is now done so the temporary folder may now be removed SC TI rm fr local 2 2 4 Configuring PTXdist When using PTXdist for the first time some setup properties have to be configured Two settings are the most important ones Where to store the source archives and ifa proxy must be used to gain access to the world wide web Run PTXdist s setup ptxdist setup Due to PTXdist is working with sources only it needs various source archives from the world wide web If these archives are not present on our host PTXdist starts the wget command to download them on demand
116. rsion all the time e using a constant OSELAS Toolchain version all the time 80 f Pengutronix 6 Various Aspects of Daily Work e no package with a pre build archive in the project is under development The hash as a part of the pre build archive s filename does only reflect the package s configuration made in the menu ptxdist menuconfig Ifthis package specific configuration changes a new hash value will be the result and PTXdist can select the corresponding correct pre build archive This hash value change is an important fact as many things outside and inside the package can have a big impact of the binary result but without a hash value change Please be careful when using the pre build archives if you e intend to switch to a different toolchain with the next build e change the patch set applied to the corresponding package e g a package is under development e change the hard coded configure settings in the package s rule file e g a package is under development e intend to use one pre build archive pool from different PTXdist projects To consider all these precautions the generated pre build archives are not transfered automatically where the next build expects them This must be done manually by the user ofthe PTXdist project Doing so we can decide on a package by package base if its pre build archive should be used or not 6 8 4 Packages without pre build archives support No host nor cross related packages
117. rve our foo binary strace usr bin foo execve usr bin foo usr bin foo x 41 vars 0 brk 0 0x8e4b000 access etc 1d so preload R_OK 1 ENOENT No such file or directory open etc 1d so cache O_RDONLY Ss 3 fstat64 3 st_mode S_IFREG 0644 st_size 77488 0 mmap2 NULL 77488 PROT_READ MAP_PRIVATE 3 0 0xb7f87000 close 3 open 1ib 1ib libm 2 5 1 so O_RDONLY 3 read 3 M177ELFNMINININONONONONONONONONONINONINONINONONOP2NONO00 512 512 mmap2 NULL 4096 PROT_READ PROT_WRITE MAP_PRIVATE MAP_ANONYMOUS 1 0 Qxb7f86000 fstat64 3 st_mode S_IFREG 0555 st_size 48272 0 mmap2 NULL 124824 PROT_READ PROT_EXEC MAP_PRIVATE MAP_DENYWRITE 3 0 Qxb7f67000 mmap2 0xb7f72000 4096 PROT_READ PROT_WRITE MAP_PRIVATE MAP_FIXED MAP_DENYWRITE 3 xb 0xb7f72000 mmap2 0xb7f73000 75672 PROT_READ PROT_WRITE MAP_PRIVATE MAP_FIXED MAP_ANONYMOUS 1 0 0xb7f73000 close 3 open 1lib libc so 6 O_RDONLY 33 read 3 177ELF 1 1 1 Q OQ O O O O O O O 3 O 3 0 1 O O O 332X 1 512 512 fstat64 3 st_mode S_IFREG 0755 st_size 1405859 0 ea Occasionally the output of strace can be very long and the interesting parts are lost So if we assume the binary tries to open a nonexisting file we can limit the output to all open system calls 6 f Pengutronix a 6 Various Aspects of Daily Work strace e open u
118. s The template file COPYING contains some links to GPL LGPL texts you can use Replace the COPYING s content by one of the listed licence files or something different But do not omit this step Never f Pengutronix 83 6 Various Aspects of Daily Work 6 10 3 Build system related files autogen sh The autotools are using macro files which are easier to read for a human But to work with the autotools these macro files must be converted into executabe shell code first The autogen sh script does this job for us configure ac This is the first part ofthe autotools based build system lts purpose is to collect as much required information as possible about the target to build the library for This file is a macro file It uses a bunch of M4 macros to define thejob to do The autotools are complex and this macro file should help you to create a useful and cross compile aware configure script everybody can use This macro file is full of examples and comments Many M4 macros are commented out and you can decide if you need them to detect special features about the target Search for the TODO keyword and adapt the setting to your needs After that you should remove the TODO comments to not confuse any user later on Special hints about some M4 macros AC_INIT add the intended revision number the second argument an email address to report bugs and some web info about your library The intended revision number will be part o
119. s can define a subset of all selected packages for specific platforms This is an advanced feature rarely used toolchain Sets upthe path to the toolchain used to compile the current selected platform Without an additional parameter PTXdist tries to guess the toolchain from platform settings To be successful PTXdist depends on the OSELAS Toolchains installed to the opt directory If PTXdist wasn t able to autodetect the toolchain an additional parameter can be given to provide the path to the compiler assembler linker and so on select Used to select the current userland configuration which is only required if there is no selected_ptxconfig in the project s main directory This parameter needs the path to a valid ptxconfig It will generate a soft link called selected_ptxconfig in the project s main directory platform Used to select the current platform configuration which is only required if there is no se lected_platformconfig in the project s main directory This parameter needs the path to a valid platformconfig It will generate a soft link called selected_platformconfig in the project s main di rectory collection Used to select the current collection configuration which is only required in special cases This pa rameter needs the path to a valid collection It will generate a soft link called selected_collection in the project s main directory This is an advanced feature rarely used go The mostly used command Thi
120. s 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 ina way defined in the menu project specific compile The package gets built install The package installs itself into a project local directory This step is important at least for libraries other packages may depend on targetinstall Relevant parts of the package will be used to build an IPKG archive and the root filesystem For each single package one so called rule file exists describing the steps to be done in each stage shown above refer section 5 3 for further details Due to the get stage PTXdist needs a working internet connection to download an archive currently not existing on the development host But there are ways to prevent PTXdist from doing so refer to section 2 2 4 20 f Pengutronix 3 PTXdist User s Manual i oka 1 ligne iP IT make sbin bar IN Br gt make _ MMT gt E usr bin baz 7 cs g baz tgz baz ipk extract compile binaries p aon PTXdist bin foo FCI o o po x o 0 po x Figure 3 2 The build process 3 2 First steps with PTXdist PTXdist works as a console command tool Everything we want PTXdist to do we have to enter as a command But it s always the same base command ptxdist lt parameter gt To run different functions this command must
121. s for the target f Pengutronix 33 4 PTXdist Developer s Manual 4 2 mb src autoconf 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 create a small autotools based source template project on demand to give the developer an easy point to start This template is prepared to build a single executable program src autoconf 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 create a small autotools libtool based source template project on demand to give the developer an easy point to start This template is prepared to build a single shared library For further details refer section 6 10 src autoconf 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 create a small autotools libtool based template project on demand to give the developer an easy point to start This template is prepared to 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 to add a few simple files into the build process We assume these fil
122. s will start to build everything to get all the project defined software parts Also used to rebuild a part after its configuration was changed images Used at the end of a build to create an image from all userland packages to deploy the target its flash for example or its hard disk setup Mostly run once per PTXdist revision to set up global paths and the PTXdist behavior All these commands depending on various files a PTXdist based project provides So running the commands make only sense in directorys that contains a PTXdist based project Otherwise PTXdist gets confused and con fuses the user with funny error messages To show the usage of some listed major subcommands we are using a generic PTXdist based project 3 2 1 Extracting the Board Support Package In order to work with a PTXdist based project we have to extract the archive first tar zxf OSELAS BSP Pengutronix Generic 2014 07 0 tar gz cd OSELAS BSP Pengutronix Generic 2014 07 0 PTXdist is project centric so now after changing into the new directory we have access to all valid components total 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 22 f Pengutronix 3 PTXdist User s Manual 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 40
123. s2 filesystem e uRamdisk a u boot loadable Ramdisk initrd gz a traditional initrd RAM disk to 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 i586 images if enabled 3 2 8 Running all Parts in an emulated Environment QEMU The OSELAS BSP Pengutronix Generic 2014 07 0 is prepared to give every user a chance to run the results ofthe previous steps even in the absense of real hardware All we need is a working QEMU on our development host Simply run configs i586 qemu run This will start QEMU in full system emulation mode and runs the previously built kernel which then uses the generated disk image to bring up a full Linux based system The running system uses a serial device for its communication QEMU forwards this emulated device to 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 to forward the standard telnet port 23 of the emulated system to host s port 4444 To connect to the emulated system we can just run a telnet localhost 4444 MAA 1 00 ooo Connected to localhost Escape character is ptx login root root ptx
124. sr bin foo open etc 1d so cache O_RDONLY 3 open lib libm 2 5 1 s0 O_RDONLY 3 open 1lib libz so 1 2 3 O_RDONLY 3 open 1lib libc so 6 O_RDONLY 3 Dae open etc foo conf O_RDONLY 1 ENOENT No such file or directory The binary may fail due to 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 LIKELIHOOD MAYBE You SHOULD VISIT US SOMEDAY Q A go 3 x PRETTY UNLIKELY WE SHOULD FIX THIS SOMEDAY NEVER EVER frengutronix O Pengutronix 7 6 Various Aspects of Daily Work If we do not need some target related feature to run our application we can also debug it through a simple CPU emulation Thanks to 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 PTXdist creates a fully working root filesystem with all runtime components in platform i586 root Lets assume we made a PTXdist based project fora i586 CPU Part of this project is our application myapp we are currently work ing on PTXdist builds the root filesystem and also compiles our application It also installs it to usr bin myapp in the root filesystem With this preparation we can run it on our build host cd platform i586 root platform i586 root qemu i386 cpu i586 L usr bin myapp This comma
125. ssible for GDB to find debug symbols for components like the main C runtime library In this case they where stripped while building the toolchain There is a switch in the OSELAS Toolchain menu to 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 toolchain was built with the debug symbols kept it will be also possible for GDB to debug C library functions our application calls so it might worth the disk space 6 4 Migration between Releases To migrate an existing project from within one minor release to the next one we do the following step my_bsp ptxdist migrate PTXdist will ask us for every new configuration entry what to do We must read and answer these questions care fully At least we shouldn t answer blindly with Y all the time because this could lead into a broken configuration On the other hand using N all to time is more safer We can still enable interesting new features later on 6 5 Software Installation and Upgrade Root filesystems for Linux are usually built as a flash image and pushed into the respective root medium How ever when working with Embedded Linux systems developers often have the need to e install new packages e remove packages e update packages e 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 be
126. stead it adds the font to the existing font IPGK This includes the generation of the directory index files required by the Xorg framework to recognize the font file src linux driver This kind of package builds an out of tree kernel driver It also creates a driver template to give the developer an easy point to start Rule File Creation To create such a new package we create a project local rules directory first Then we run ptxdist newpackage lt package type gt If we omit the lt package type gt PTXdist will list all available package types In our first example we want to add a new target type archive package When running the ptxdist newpackage target command PTXdist asks a few questions about this package This information is the basic data PTXdist must know about the package f Pengutronix 3 4 PTXdist Developer s Manual 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 pedis tente tez ptxdist enter package author My Name lt me my org com gt ptxdist enter package section project_specific What we have to 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 tar gz then foo is the basename to enter here version number
127. t depends on the currently selected platform and its architecture what content this variable will have The content shown above is an example for an x86 target Or re build the package with the new settings ptxdist drop foo prepare ptxdist targetinstall foo Adding Dynamic Configure Parameters Sometimes it makes sense to add this kind of parameters on demand only especially a parameter like enable debug To let the user decide if this parameter is to 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 to add on demand to the configure pa rameters 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 Note To extend the base name by a suboption name as a trailing component gives PTXdist the ability to detect a change in the package s settings to force its rebuild To make usage of the new menu entries we must check them in the rule file and add the correct parameters 42 f Pengutronix 4 PTXdist Developer s Manual autoconf FOO_AUTOCONF CROSS_AUTOCONF_USR ifdef PTXCONF_FOO_DEBUG FOO_AUTOCONF enable debug else FOO_AUTOCONF disable debug endi
128. tall directory to the root filesystem call install_copy foo 0 0 0755 usr bin foo 5 2 5 install_tree Usage call install_tree lt package gt lt UID gt lt GID gt lt source dir gt lt destination dir gt Installs the whole directory tree with all files from the given directory into e the project s platform i586 root e the project s platform 1586 root debug e anipkg packet in the project s platform i586 packages Some of the parameters have fixed meanings lt package gt Name of the IPKG OPKG the macro should work on lt UID gt User ID the directories and files should use in the target s root filesystem or to keep the UID from the source tree lt GID gt Group ID the directories and files should use in the target s root filesystem or to keep the GID from the source tree lt source dir gt This is the path to the tree of directories and files to be installed It can be to use the package directory of the current package instead lt destination dir gt The basename of the to be installed tree in the root filesystem Note This installation macro e uses the same permission flags in the destination dir as found in the source dir This is valid for directories and regular files e skips all directories with names like svn git pc and CVS in the source directory Examples Install the whole tree found in home jbe foo to the root filesystem at location usr share bar call install_tree fo
129. ten temporarily by the command line parameter ptxconfig lt different project config gt f Pengutronix 14 6 Various Aspects of Daily Work The used Toolchain to Build ptxdist toolchain lt some toolchain path gt This call will create the soft link selected_toolchain to the lt some toolchain path gt in the project s directory After this call PTXdist uses this soft link as the default toolchain to build the project with It can be overwritten temporarily by the command line parameter toolchain lt different toolchain path gt By creating the soft links all further PTXdist commands will use these as the default settings By using the three platformconfig ptxconfig and toolchain parameters we can switch temporarily to a completely different setting This feature we can use to build everything in one project A few Examples The project contains two individual platforms sharing the same architecture and same project configuration ptxdist select lt project config gt ptxdist toolchain lt architecture toolchain path gt ptxdist platformconfig lt architecture A gt quiet go amp ptxdist platformconfig lt architecture B gt go The project contains two individual platforms sharing the same project configuration ptxdist select lt project config gt ptxdist platformconfig lt architecture A gt toolchain lt architecture A toolchain path gt quiet go amp ptxdist platformconfi
130. ts like this usr local lib ptxdist 2014 07 0 projects office my_projects ptxdist Leave the menu and store the configuration PTXdist is now ready for use must repeat the previous steps with the PTXdist 2013 12 0 to install it on our host as well All i In order to build the toolchain in the next step the specific PTXdist 2013 12 0 is required We PTXdist revisions can co exist fPengutronn 13 Pengutronix 2 Getting a working Environment 2 3 Toolchains Before we can start building our first userland we need a cross toolchain On Linux toolchains are no monolithic beasts Most parts of what we need to 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 tools cc1 g Id 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 tools are usually named like the corresponding host tool but with a prefix the GNU target For example the cross compilers for ARM and powerpc may look like e arm softfloat linux gnu gcc e powerpc unknown 1inux gnu gcc With these compiler frontends we can convert e g a C program into binary code for specific machines So for example ifa C program is to be compiled natively it works like this gcc test c o test To build the same bin
131. ut if PTXdist cannot fulfill this dependency we also must add it as a separate package first Ifthe prepare stage has finished successfully the next step is to compile the package ptxdist compile foo make 1 Entering directory home jbe my_new_prj build target foo 1 1 0 make all recursive make 2 Entering directory home jbe my_new_prj build target foo 1 1 0 make 3 Entering directory home jbe my_new_prj build target foo 1 1 0 eae make 3 Leaving directory home jbe my_new_prj build target foo 1 1 0 make 2 Leaving directory home jbe my_new_prj build target foo 1 1 0 make 1 Leaving directory 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 to execute just created target binaries for example The package depends on external components libraries for example not detected by configure e 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 1ib for example by accident In all of these cases we must patch the sources to make them work Refer to section 4 2 4 on how to use PTXdist s features to 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
132. your settings in configure ac URL where to find your library Will automatically replaced from your settings in configure ac Requires private comma separated list of packages your library depends on and managed by pkg config The listed packages gets honored for the static linking case and should not be given again in the Libs private line This line will be filled by the REQUIRES variable from the configure ac Conflicts list of packages your library conflicts with Will automatically replaced from your CONFLICTS variable settings in configure ac Libs defines the linker command line content to link your library against other applications or libraries Libs private defines the linker command line content to link your library against other application or libraries statically List only libraries here which are not managed by pkg config e g do not conflict with packages given in the Requires This line will be filled by the LIBS variable from the configure ac Cflags required compile flags to make use of your library Unfortunately you must mix CPPFLAGS and CFLAGS here which is a really bad idea It is not easy to fully automate the adaption of the pc file At least the lines Requires private and Libs private are hardly to fill for packages which are highly configureable 6 10 5 Generic template files m4 M4 macros used in configure ac If you use more no generic Mq macros in your configure ac file don t forget to add their source
133. ystem type 1686 host linux gnu checking host system type 1586 unknown 1inux gnu checking whether to 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 1586 unknown linux gnu strip checking for i586 unknown linux gnu gec 1586 unknown 1inux gnu gcc checking for C compiler default output file name a out configure creating config status config status creating Makefile config status creating ppa_protocol Makefile config status creating config h f Pengutronix 4 PTXdist Developer s Manual config status executing depfiles commands finished target foo prepare At this stage things can fail A wrong or no MDs sum was given e The configure script is not cross compile aware e The package depends on external components libraries for example Ifthe configure script is not cross compile aware we are out of luck We must patch the source archive in this case to make it work Refer to section 4 2 6 on how to use PTXdist s features to simplify this task If the package depends on external components these components might be already part of PTXdist In this case we just have to add this dependency into the menu file and we are done B

OSELAS.Support OSELAS.Training OSELAS

Contents

Download Pdf Manuals

Related Search

Related Contents