Difference between revisions of "Building Existing Software Packages with EMAC OE SDK"

From wiki.emacinc.com
Jump to: navigation, search
m (libConfuse Example Project: Fixed incorrect tag usage.)
 
(19 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{| class="wikitable conventions"
+
{{todo| SEOKWREV <strike>update this with our own mirror locations; add missing summary for oe 4;</strike> add CMake info for OE 5 (12.17.13-11:50->KY+);(03.04.14-16:20->BS-);(03.20.14-16:05->BS+);(04.14.14-14:45->BS+)|Michael Gloff|project=oe 4,mg,ky,SEOKWREV,md,bs}}
!colspan="2"|Table 1: Conventions
+
 
|-
+
{{#seo:
| <code>/path/to/sdk/</code> || Represents the development system path to the EMAC OE SDK.
+
|title=Building Existing Software Packages with EMAC OE SDK
|-
+
|titlemode=append
| <code>EMAC-OE-arm-linux-gnueabi-SDK_XX.YY.rZZ.tar.bz2</code><br /><code>EMAC-OE-arm-linux-gnueabi-SDK_XX.YY</code>
+
|keywords=EMAC Software Packages,EMAC HelloMake Project,libConfuse Example
|| '''XX''' is the major version<br />'''YY''' is the minor version<br />'''ZZ''' is the current revision<br />The major and minor version numbers will match the version of OE for which the SDK is created.
+
|description=Building Existing Software Packages with EMAC OE SDK.
|}
+
}}
 +
It is often necessary to build an existing project from source code. This is the case when a specific program is required to run on the target device and pre-compiled binaries do not exist. In the steps below, the EMAC SDK toolchain will be used to compile an existing <code>Makefile</code> based project and an <code>Autotools</code> based project that can be run on the target device.  
  
It is very common to need to be able to build existing software projects for the target hardware rather than developing the software from scratch. This feature is especially important in an open source environment, where countless libraries and utilities are available for use and often times need to be compiled to match the target architecture. Fortunately, EMAC OE SDK toolchains are standard GCC packages designed and configured to make this process as easy as possible. In addition, most software projects are developed to allow for cross-platform development.
 
  
This guide provides an overview of the most common tasks associated with compiling existing software projects using the SDK. Note, however, that build methods differ significantly depending on the project design. Refer to the project documentation or support for information on how to cross-compile the software; the EMAC OE SDK can be treated as a standard GCC toolchain in this respect. Table 1 below denotes some conventions used in this guide.
 
  
 
==Makefile-based Projects==
 
==Makefile-based Projects==
  
Some projects have a build system based on a set of makefiles that are responsible for compiling and packaging the software. In general, configuring these projects to compile using the EMAC OE SDK is a simple process. In some instances, the software designers may have included a variable in the makefile which allows a cross-compiler prefix setting. In other cases, the CC and other makefile variables can be modified to direct make to compile using the EMAC OE SDK.
+
The GNU ''make'' utility uses one or more Makefiles to direct the compiler to what source files to build and what options to use when building. Makefile based projects are generally set up for larger complex projects to simplify the configuration of the project. The example below uses a relatively simple project that can be extended as needed.
 
 
It may be advantageous to add the cross-compiler bin directory to the system PATH variable temporarily before compiling to simplify Makefile modifications. This can be done with a command such as the following:
 
  
<syntaxhighlight lang="bash">
+
===HelloMake Project Example===
developer@ldc:~$ export PATH=$PATH:/path/to/sdk/EMAC-OE-arm-linux-gnueabi-SDK_XX.YY/gcc-4.2.4-arm-linux-gnueabi/bin
 
</syntaxhighlight>
 
  
{{mbox | type = notice | text = Note that running the command above will only affect the current terminal session.}}
+
The HelloMake project contains two source files, a header file, and a Makefile. The Makefile will direct ''make'' to use the correct target compiler and libraries to compile the source and header files into an executable. The header file is located in the include directory as is common with larger projects. The obj files created will be stored in the obj directory to keep from cluttering the source directory and the executable will be placed in the bin directory. The Makefile also contains a clean target to remove all of the temporary and intermediate files and an upload target to upload the executable to the target device.
  
===MTD Utilities Project Example===
+
<cl>
 +
1. Begin by downloading the [ftp://ftp.emacinc.com/Controllers/Development_Kits/EMAC_Open_Tools/Linux/misc_software/HelloMake.tar.gz HelloMake] project
  
The MTD Utilities project <code>mtd-utils</code> is a good example of a Makefile-based build system that can easily be built using the EMAC OE SDK. Follow the steps below to accomplish this task.
+
* Extract the project.<syntaxhighlight lang=console>developer@ldc:~$ tar zxvf HelloMake.tar.gz</syntaxhighlight>
  
{{mbox | type = notice | text = The instructions in this section are valid as of the master git branch on 4/09/11. Future source changes may impact the required steps for compilation.}}
+
* Modify the first line of ''Makefile'' in the src directory to point to the path to the correct global.properties file. Make sure that the [[ Configuring_EMAC_OE_4.0_SDK | setmachine ]] script has been run before attempting to build the project. This allows ''make'' to use the correct compiler and compile options for the target machine.
  
# Begin by downloading the mtd-utils source code. Assuming that git is installed on the development system, run the following command to get the most recent version. Note that this version will be different from the stable release installed on EMAC OE systems by default.
 
<syntaxhighlight lang="bash">
 
developer@ldc:~$ git clone git://git.infradead.org/mtd-utils.git
 
</syntaxhighlight>
 
# After downloading the source, navigate to the source directory <code>mtd-utils</code> and open <code>Makefile</code> in the top-level directory. This file defines various make targets and compilation flags used to compile the source. Notice that the file <code>common.mk</code> is sourced with the line include <code>common.mk</code>. This is similar to the <code>global.properties</code> file in the EMAC OE SDK.
 
# Close the <code>Makefile</code> editor and open the <code>common.mk</code> file. At the top of the file, <code>CC</code>, <code>AR</code>, and <code>RANLIB</code> are defined using the <code>CROSS</code> variable, which is not set in either <code>common.mk</code> or <code>Makefile</code>. An exert is shown below:
 
 
<syntaxhighlight lang="make">
 
<syntaxhighlight lang="make">
CC := $(CROSS)gcc
+
include /path/to/sdk/projects/global.properties
AR := $(CROSS)ar
 
RANLIB := $(CROSS)ranlib
 
</syntaxhighlight>
 
If the <code>CROSS</code> variable is defined when <code>make</code> is run, the specific toolchain to use can be specified. Also note that <code>CFLAGS</code> is defined using a <code>?=</code> assignment, which means that the assignment will only be made if <code>CFLAGS</code> is undefined:
 
<syntaxhighlight lang="make">
 
CFLAGS ?= -O2 -g
 
</syntaxhighlight>
 
# Close <code>common.mk</code> without making any changes.
 
# In order to compile the source correctly, the <code>CROSS</code> and <code>CFLAGS</code> variables should be defined. The tuning flags for the target architecture to be added to the <code>CFLAGS</code> variable should be used from the <code>ARCHFLAGS</code> variable in the <code>global.properties</code> file of the EMAC OE SDK. The following steps utilize tuning flags for an armv5te processor-based system. Although the path to the SDK toolchain could be included directly in the <code>CROSS</code> variable in this instance, this example works by adding the SDK toolchain to the system <code>PATH</code> variable. The path and prefix used will differ depending on the target architecture of the EMAC OE SDK; refer to <code>global.properties</code> in the SDK to determine the correct settings. The <code>DESTDIR</code> variable controls where the files are put when running the <code>install</code> make target. The <code>WITHOUT_XATTR</code> flag must be set to disable features of the software that are not available on EMAC OE.
 
## Before compiling, several source changes are required to match the setup of the SDK. These include changing references from <code>lzo2</code> to <code>lzo</code>, and changing the lzo include prefix. Run the following commands from the mtd-utils directory to make these changes:
 
<syntaxhighlight lang="bash">
 
developer@ldc:~$ for file in `find . -name Makefile`; do sed -i 's:lzo2:lzo:g' $file; done
 
developer@ldc:~$ for file in `find . -name '*.c'`; do sed -i 's:lzo/::g' $file; done
 
</syntaxhighlight>
 
## Run the following commands to set the variables:
 
<syntaxhighlight lang="bash">
 
developer@ldc:~$ export PATH=$PATH:/path/to/sdk/EMAC-OE-arm-linux-gnueabi-SDK_XX.YY/gcc-4.2.4-arm-linux-gnueabi/bin
 
developer@ldc:~$ export CROSS=arm-linux-gnueabi-
 
developer@ldc:~$ export CFLAGS="-O2 -g -march=armv5te -mtune=arm926ej-s"
 
developer@ldc:~$ export DESTDIR=Install
 
developer@ldc:~$ export WITHOUT_XATTR=1
 
</syntaxhighlight>
 
# Once the environment has been set up, <code>make</code> can be used to compile the source code:
 
<syntaxhighlight lang="bash">
 
developer@ldc:~$ make all
 
</syntaxhighlight>
 
# After successfully compiling the project, the <code>install</code> make target can be used to package all of the software into the <code>Install</code> directory as specified by the <code>DESTDIR</code> variable:
 
<syntaxhighlight lang="bash">
 
developer@ldc:~$ make install
 
developer@ldc:~$ ls -R Install
 
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
* From the command prompt in the src directory type ''make''
 +
<syntaxhighlight lang="console">
 +
developer@EMAC-LDC-32bit:~/EMAC-OE-arm-linux-gnueabi-SDK_4.0/HelloMake/src$ make
 +
 +
../../gcc-4.3.1-arm-emac-linux-gnueabi/bin/arm-emac-linux-gnueabi-gcc  -MMD -g -march=armv7-a -mtune=cortex-a8 -mfpu=neon -c -o obj/hellomake.o hellomake.c
 +
../../gcc-4.3.1-arm-emac-linux-gnueabi/bin/arm-emac-linux-gnueabi-gcc  -MMD -g -march=armv7-a -mtune=cortex-a8 -mfpu=neon -c -o obj/hellofunc.o hellofunc.c
 +
../../gcc-4.3.1-arm-emac-linux-gnueabi/bin/arm-emac-linux-gnueabi-gcc  -lm -o ../bin/hellomake obj/hellomake.o obj/hellofunc.o
 +
</syntaxhighlight>
 +
 +
* After successfully compiling the project, the <code>upload</code> ''make'' target can be used to transfer the executable to the target machine as specified by the upload line in ''Makefile''.
 +
 
<syntaxhighlight lang="console">
 
<syntaxhighlight lang="console">
Install:
+
developer@ldc:~$ make upload
usr
 
 
Install/usr:
 
sbin  share
 
 
Install/usr/sbin:
 
docfdisk      flash_erase    flash_lock      flash_unlock  jffs2dump  nanddump  nftldump    rfddump      sumtool
 
doc_loadbios  flash_eraseall  flash_otp_dump  ftl_check    mkfs.jffs2  nandtest  nftl_format  rfdformat
 
flashcp      flash_info      flash_otp_info  ftl_format    mtd_debug  nandwrite  recv_image  serve_image
 
 
Install/usr/share:
 
man
 
 
Install/usr/share/man:
 
man1
 
 
Install/usr/share/man/man1:
 
mkfs.jffs2.1.gz
 
 
</syntaxhighlight>
 
</syntaxhighlight>
While the procedure in this example is specific to <code>mtd-utils</code>, many makefile-based projects will require similar steps for cross-compiling.
+
 
 +
</cl>
  
 
==Autotools-based Projects==
 
==Autotools-based Projects==
Line 102: Line 57:
 
The libConfuse project is a simple C library written for parsing configuration files. It uses an autotools build system for configuration. The steps below demonstrate how to build libConfuse and should be used as an example for building other autotools-based projects.  
 
The libConfuse project is a simple C library written for parsing configuration files. It uses an autotools build system for configuration. The steps below demonstrate how to build libConfuse and should be used as an example for building other autotools-based projects.  
  
# The source code for the libConfuse project can be downloaded as described on the project website [http://www.nongnu.org/confuse/]. For this example, release 2.7 is used: [http://savannah.nongnu.org/download/confuse/confuse-2.7.tar.gz]. After downloading the source, extract the archive and navigate to the top-level directory of the project (i.e. `confuse-2.7`).
+
<cl>
# Read through the <code>README</code> and <code>INSTALL</code> files for information on the project and general information on how to build it. Also, look at the help output from <code>configure</code> to see a summary of the available options:
+
1. The source code for the libConfuse project can be downloaded as described on the project [http://www.nongnu.org/confuse/ website]. For this example, [ftp://ftp.emacinc.com/Controllers/Development_Kits/EMAC_Open_Tools/Linux/misc_software/confuse-2.7.tar.gz release 2.7] is used. After downloading the source, extract the archive and navigate to the top-level directory of the project.
 +
 
 +
* Read through the <code>README</code> and <code>INSTALL</code> files for information on the project and general information on how to build it. Also, look at the help output from <code>configure</code> to see a summary of the available options:
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
 
developer@ldc:~$ ./configure --help
 
developer@ldc:~$ ./configure --help
 
</syntaxhighlight>
 
</syntaxhighlight>
# Before beginning, the system <code>PATH</code> variable should be changed to include the SDK toolchain as in the makefile-based project example. The <code>CFLAGS</code> variable should also be set. If the <code>CC</code> variable is set, it should be set to <code>arm-linux-gnueabi-gcc</code> (or the appropriate value for the target); if not set the compiler name will be detected from the options passed to configure. The <code>CFLAGS</code> architecture tuning values should be set according to the <code>global.properties</code> file in the EMAC OE SDK. The <code>DESTDIR</code> variable determines where the files will be installed to when the <code>install</code> make target is run. <code>DESTDIR</code> must be an absolute path for the libConfuse project, so the current working directory is added to the variable using the <code>pwd</code> command. The following commands are an example of how to set up the environment correctly:
+
 
 +
* In order for autotools to use the correct compiler and compile options, the <code>CFLAGS, CC,</code> and  <code>CXX</code> variables need to be set. Open the correct global.properties file to see what the values should be. The example below is for an armv5 processor.
 +
 
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
 +
developer@ldc:~$ export CC="/path/to/sdk/gcc-4.2.4-arm-linux-gnueabi/bin/arm-linux-gnueabi-gcc"
 +
developer@ldc:~$ export CXX="/path/to/sdk/gcc-4.2.4-arm-linux-gnueabi/bin/arm-linux-gnueabi-g++"
 
developer@ldc:~$ export CFLAGS="-O2 -march=armv5te -mtune=arm926ej-s"
 
developer@ldc:~$ export CFLAGS="-O2 -march=armv5te -mtune=arm926ej-s"
 
developer@ldc:~$ export DESTDIR=`pwd`/Install
 
developer@ldc:~$ export DESTDIR=`pwd`/Install
 
</syntaxhighlight>
 
</syntaxhighlight>
# After setting the environment, <code>configure</code> can be run with the appropriate options to configure the build system and generate the makefiles. The code below shows an example configuration used by EMAC OE. Be sure to set the host and target correctly based on the architecture:
+
 
 +
* After setting the environment, <code>configure</code> can be run with the appropriate options to configure the build system and generate the makefiles. The code below shows an example configuration. Be sure to set the host and target correctly based on the architecture:
 +
 
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
 
developer@ldc:~$ ./configure --build=i686-linux --host=arm-linux-gnueabi --target=arm-linux-gnueabi \
 
developer@ldc:~$ ./configure --build=i686-linux --host=arm-linux-gnueabi --target=arm-linux-gnueabi \
Line 120: Line 83:
 
         --mandir=/usr/share/man --enable-shared
 
         --mandir=/usr/share/man --enable-shared
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 
The configuration should complete successfully. If any problems are reported that result in an error, check the environment settings and <code>configure</code> options again.  
 
The configuration should complete successfully. If any problems are reported that result in an error, check the environment settings and <code>configure</code> options again.  
# Now that <code>configure</code> has generated all of the makefiles for the project, <code>make</code> can be used to compile the source code:
+
 
 +
* Now that <code>configure</code> has generated all of the makefiles for the project, <code>make</code> can be used to compile the source code:
 +
 
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
 
developer@ldc:~$ make all
 
developer@ldc:~$ make all
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 
If any errors are encountered during compilation, examine the output of <code>configure</code> and make sure that all of the environment variables and <code>configure</code> options were specified correctly.  
 
If any errors are encountered during compilation, examine the output of <code>configure</code> and make sure that all of the environment variables and <code>configure</code> options were specified correctly.  
# Once compilation is complete, the <code>install</code> target can be used to package all of the necessary files together so that they can be transferred to the target board.
+
 
 +
* Once compilation is complete, the <code>install</code> target can be used to package all of the necessary files together so that they can be transferred to the target board.
 +
 
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
 
developer@ldc:~$ make install
 
developer@ldc:~$ make install
 
developer@ldc:~$ ls -R Install
 
developer@ldc:~$ ls -R Install
</syntaxhighlight>
 
<syntaxhighlight lang="console">
 
 
Install:
 
Install:
 
usr
 
usr
Line 165: Line 132:
 
confuse.mo
 
confuse.mo
 
</syntaxhighlight>
 
</syntaxhighlight>
Note that not all of the files installed would be necessary to install on the board, such as the man pages and pkgconfig information.
+
 
 +
</cl>
 +
 
 +
==See Also==
 +
 
 +
[http://www.gnu.org/software/make/manual/make.html GNU ''make'' documentation].
 +
 
 +
[http://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html Autotools documentation].
 +
 
 +
<!--[[Category:EMAC OE SDK]]-->

Latest revision as of 14:41, 24 November 2014

TODO: {{#todo: SEOKWREV update this with our own mirror locations; add missing summary for oe 4; add CMake info for OE 5 (12.17.13-11:50->KY+);(03.04.14-16:20->BS-);(03.20.14-16:05->BS+);(04.14.14-14:45->BS+)|Michael Gloff|oe 4,mg,ky,SEOKWREV,md,bs}}

It is often necessary to build an existing project from source code. This is the case when a specific program is required to run on the target device and pre-compiled binaries do not exist. In the steps below, the EMAC SDK toolchain will be used to compile an existing Makefile based project and an Autotools based project that can be run on the target device.


Makefile-based Projects

The GNU make utility uses one or more Makefiles to direct the compiler to what source files to build and what options to use when building. Makefile based projects are generally set up for larger complex projects to simplify the configuration of the project. The example below uses a relatively simple project that can be extended as needed.

HelloMake Project Example

The HelloMake project contains two source files, a header file, and a Makefile. The Makefile will direct make to use the correct target compiler and libraries to compile the source and header files into an executable. The header file is located in the include directory as is common with larger projects. The obj files created will be stored in the obj directory to keep from cluttering the source directory and the executable will be placed in the bin directory. The Makefile also contains a clean target to remove all of the temporary and intermediate files and an upload target to upload the executable to the target device.


  1. Begin by downloading the HelloMake project

  2. Extract the project.
    developer@ldc:~$ tar zxvf HelloMake.tar.gz
    
  3. Modify the first line of Makefile in the src directory to point to the path to the correct global.properties file. Make sure that the setmachine script has been run before attempting to build the project. This allows make to use the correct compiler and compile options for the target machine.

    include /path/to/sdk/projects/global.properties
    
  4. From the command prompt in the src directory type make

    developer@EMAC-LDC-32bit:~/EMAC-OE-arm-linux-gnueabi-SDK_4.0/HelloMake/src$ make
    
    ../../gcc-4.3.1-arm-emac-linux-gnueabi/bin/arm-emac-linux-gnueabi-gcc  -MMD -g -march=armv7-a -mtune=cortex-a8 -mfpu=neon -c -o obj/hellomake.o hellomake.c
    ../../gcc-4.3.1-arm-emac-linux-gnueabi/bin/arm-emac-linux-gnueabi-gcc  -MMD -g -march=armv7-a -mtune=cortex-a8 -mfpu=neon -c -o obj/hellofunc.o hellofunc.c
    ../../gcc-4.3.1-arm-emac-linux-gnueabi/bin/arm-emac-linux-gnueabi-gcc   -lm -o ../bin/hellomake obj/hellomake.o obj/hellofunc.o
    
  5. After successfully compiling the project, the upload make target can be used to transfer the executable to the target machine as specified by the upload line in Makefile.

    developer@ldc:~$ make upload
    


Autotools-based Projects

The GNU build system is known as Autotools. Autotools is a group of applications that are designed to provide a configurable build system to allow compilation on different platforms and environments. A configure script and set of input files are used to generate makefiles based on options passed to the configure script and deduced from the system environment. This includes tests for compiler options, library functions, install configuration, and other assorted variables.

The configure script is the most important step in building an autotools-based project. Although available options for configure vary depending on the project design, there are common options shared between most autotools projects.

libConfuse Example Project

The libConfuse project is a simple C library written for parsing configuration files. It uses an autotools build system for configuration. The steps below demonstrate how to build libConfuse and should be used as an example for building other autotools-based projects.


  1. The source code for the libConfuse project can be downloaded as described on the project website. For this example, release 2.7 is used. After downloading the source, extract the archive and navigate to the top-level directory of the project.

  2. Read through the README and INSTALL files for information on the project and general information on how to build it. Also, look at the help output from configure to see a summary of the available options:

    developer@ldc:~$ ./configure --help
    
  3. In order for autotools to use the correct compiler and compile options, the CFLAGS, CC, and CXX variables need to be set. Open the correct global.properties file to see what the values should be. The example below is for an armv5 processor.

    developer@ldc:~$ export CC="/path/to/sdk/gcc-4.2.4-arm-linux-gnueabi/bin/arm-linux-gnueabi-gcc"
    developer@ldc:~$ export CXX="/path/to/sdk/gcc-4.2.4-arm-linux-gnueabi/bin/arm-linux-gnueabi-g++"
    developer@ldc:~$ export CFLAGS="-O2 -march=armv5te -mtune=arm926ej-s"
    developer@ldc:~$ export DESTDIR=`pwd`/Install
    
  4. After setting the environment, configure can be run with the appropriate options to configure the build system and generate the makefiles. The code below shows an example configuration. Be sure to set the host and target correctly based on the architecture:

    developer@ldc:~$ ./configure --build=i686-linux --host=arm-linux-gnueabi --target=arm-linux-gnueabi \
            --prefix=/usr --exec_prefix=/usr --bindir=/usr/bin --sbindir=/usr/sbin \
            --datadir=/usr/share  \
            --infodir=/usr/share/info \
            --mandir=/usr/share/man --enable-shared
    

    The configuration should complete successfully. If any problems are reported that result in an error, check the environment settings and configure options again.

  5. Now that configure has generated all of the makefiles for the project, make can be used to compile the source code:

    developer@ldc:~$ make all
    

    If any errors are encountered during compilation, examine the output of configure and make sure that all of the environment variables and configure options were specified correctly.

  6. Once compilation is complete, the install target can be used to package all of the necessary files together so that they can be transferred to the target board.

    developer@ldc:~$ make install
    developer@ldc:~$ ls -R Install
    Install:
    usr
    
    Install/usr:
    include  lib  share
    
    Install/usr/include:
    confuse.h
    
    Install/usr/lib:
    libconfuse.a  libconfuse.la  libconfuse.so  libconfuse.so.0  libconfuse.so.0.0.0  pkgconfig
    
    Install/usr/lib/pkgconfig:
    libconfuse.pc
    
    Install/usr/share:
    locale
    
    Install/usr/share/locale:
    fr  sv
    
    Install/usr/share/locale/fr:
    LC_MESSAGES
    
    Install/usr/share/locale/fr/LC_MESSAGES:
    confuse.mo
    
    Install/usr/share/locale/sv:
    LC_MESSAGES
    
    Install/usr/share/locale/sv/LC_MESSAGES:
    confuse.mo
    


See Also

GNU make documentation.

Autotools documentation.