View source for Creating a New EMAC OE SDK Project with CMake

{{todo| Complete (08.07.2015-12:59->KY+)(08.17.2015-12:07->KY+)(08.17.2015-14:25->KY+)(08.17.2015-17:40->MD-)(11.03.2015-13:38->KY+);(11.04.2015-11:20->MD-)(11.04.2015-13:04->KY+-);(11.04.2015-13:25->MD+)(11.04.2015-14:45->MG+)|Klint Youngmeyer| project=OE 5.0,KY,MD,Complete }}
{{#seo:
|title=Creating a New EMAC OE SDK Project with CMake
|titlemode=append
|keywords=CMakeLists.txt, CMake cross-compiling, CMake, CMake ARM, oe_init_project
|description=Creating an EMAC OE SDK project which uses the CMake build system.
}}

<!-- /*********************************************************************************************************/ -->
<!-- /****************************************  Page Description Text  ****************************************/ -->
<!-- /*********************************************************************************************************/ -->
The EMAC OE SDK is distributed with the intent that CMake be used with the EMAC OE toolchain and libraries to build most projects. This page demonstrates the process of creating and compiling a new project with CMake, and running it on the target machine.

__TOC__

<!-- /*********************************************************************************************************/ -->
<!-- /*****************************************  General Information  *****************************************/ -->
<!-- /*********************************************************************************************************/ -->
{{:Templateimpl:geninfo | initials=KY | title=Creating a New EMAC OE SDK Project with CMake | desc=Creating an EMAC OE SDK Project which Builds via CMake | project=OE 5.0 }}
Creating a new EMAC CMake project is accomplished with the use of the <code>oe_init_project</code> program. This program is included in the [ftp://oe50opkg:opkgoe50123@ftp.emacinc.com/5.1/x86_64-nativesdk/nativesdk-emac-tools_git-r0_x86_64-nativesdk.ipk emac-tools] opkg package, which is part of the ADT EMAC SDK. For instructions on installing the EMAC SDK, please see [[Installing_EMAC_OE_5.0_SDK | SDK Install]].
<!-- /*********************************************************************************************************/ -->
<!-- /*****************************************  Using/Working With  ******************************************/ -->
<!-- /*********************************************************************************************************/ -->
{{:Templateimpl:using | initials=KY | title=Creating a New EMAC OE SDK Project with CMake | desc=Creating an EMAC OE SDK project which Builds with CMake | project=OE 5.0 }}

This section demonstrates how to use the EMAC CMake tool, <code>oe_init_project</code>, to generate CMake files automatically for a project. When using the EMAC SDK there are currently two options for cross compiling:
* <code>arm</code>
* <code>x86</code>
For the purposes of this guide, the <code>arm</code> option will be used for the listed examples.
=== Host Machine Compiling ===
Navigate to the directory where the project will be located. Then run the CMake new project tool, <code>/opt/emac/5.x/bin/oe_init_project</code>.
{{clo}}
{{clio | username=developer | hostname=ldc | pwd=~ |cd projects }}
{{clio | username=developer | hostname=ldc | pwd=~/projects | 1 = export PATH=/opt/emac/5.1/bin:$PATH}}
{{clio | username=developer | hostname=ldc | pwd=~/projects |oe_init_project -n hello.c }}
If desired, please enter a name for this project, otherwise press Enter to use the default: hello_emac <br />

-- Creating new project directory... <br />
-- Creating new source file... <br />
-- Building custom CMakeLists.txt file... <br />
-- Done. <br />

Do you want to create a build directory for this project? (y/n) y <br />

-- Creating build directory... <br />

Do you want to run cmake for this project? (y/n) y <br />

-- Using system compiler <br />
-- The C compiler identification is GNU 4.8.2 <br />
-- The CXX compiler identification is GNU 4.8.2 <br />
-- Check for working C compiler: /usr/bin/cc <br />
-- Check for working C compiler: /usr/bin/cc -- works <br />
-- Detecting C compiler ABI info <br />
-- Detecting C compiler ABI info - done <br />
-- Check for working CXX compiler: /usr/bin/c++ <br />
-- Check for working CXX compiler: /usr/bin/c++ -- works <br />
-- Detecting CXX compiler ABI info <br />
-- Detecting CXX compiler ABI info - done <br />
-- Configuring done <br />
-- Generating done <br />
-- Build files have been written to: /home/developer/projects/hello_emac/hello_emac-build <br />

Do you want to compile this project? (y/n) y

Scanning dependencies of target hello_emac <br />
[100%] Building C object CMakeFiles/hello_emac.dir/hello.c.o <br />
Linking C executable hello_emac <br />
[100%] Built target hello_emac <br />
{{clos}}

The executable, in this case,  is now inside the <code> hello_emac/hello_emac-build </code> directory and can be executed by the host machine (X86_64).

The CMake project script has now made a project directory that contains the following:
* <code>CMakeLists.txt</code>
* Source code file (<code>hello.c</code> in this case)
* <code>README</code> file
* Desktop Build Directory (<code>hello_emac-build</code> in this case)

The <code>CMakeLists.txt</code> is a script which contains the required information to automatically create a <code>Makefile</code> for any supported architecture.  This file was generated by the EMAC <code>oe_init_project</code> tool, and will need to be modified over time as a project grows.  The comments in the <code>CMakeLists.txt</code> file generated by the EMAC tool will provide a good starting point for how to add additional source files and how to perform other common tasks related to maintaining your CMake build system as you develop your software project. The [http://cmake.org CMake] project provides extensive documentation on how to work with these files.

The source code file generated by the script (<code>hello.c</code>) contains a basic Hello World style program.  This can provide a starting point for your application, or can be replaced by another source file with the same name.

The <code>README</code> file contains more information on using <code>CMake</code> with the EMAC OE 5.X SDK.  You may refer to this file for quick reference.

The Desktop Build Directory (<code>hello_emac-build</code>) contains the executable, <code>hello_emac</code>, the <code>Makefile</code>, and various cache files.  These were automatically created by CMake and by the build system, and can be recreated at any time.

It is useful to have a Desktop Build Directory because it is easier (in the beginning) to use the desktop to verify all code changes before cross-compiling for a target board. This will be useful until the application under development depends upon resources which are only available on the target hardware, such as certain device drivers or the touchscreen (if so equipped).

=== Target Machine Compiling ===

Use the following steps to cross-compile the project and send it to a target board.
<br />
<cl>
1. In a terminal, navigate to the base directory of the project. {{note | If the architecture of the target board you're using for your appliction <code>x86</code>, then you will need to change all occurrences of <code>arm</code> in the following sections below to <code>x86</code>.}}
* Create a build directory for cross compiling. 
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac | mkdir hello_emac-build-arm }} 
* Navigate into the newly created directory.
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac | cd hello_emac-build-arm }} 
* Run <code>cmake</code> using the target architecture.
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac/hello_emac-build-arm | 1 = cmake .. -DARCH:STRING=arm }} 
* Compile the code using <code>make</code>.
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac/hello_emac-build-arm | make }} 
The <code> make </code> command creates the target executable in the <code>hello_emac-build-arm</code> directory.
* Now copy the executable to the target board. For information on copying the executable file, see the [[ #Transferring_Files | Transferring Files ]] section.
</cl>

<!-- /*********************************************************************************************************/ -->
<!-- /*****************************************       Examples        *****************************************/ -->
<!-- /*********************************************************************************************************/ -->
{{:Templateimpl:examples | initials=KY | title=Creating a New EMAC OE SDK Project with CMake | desc=Creating an EMAC OE SDK project for use with CMake | project=OE 5.0 }}
This section illustrates how to complete various tasks associated with configuring and building a CMake project.
===Debug Build Types===
By default, new projects will have the Debug build type. To compile the project with the Release or Minimum Size Release build types, there are two options:
*Make a secondary (or tertiary) build directory. (Recommended)
*Clean the current build directory and re-run CMake.
The different levels of build type correlate to usage of different C Flags. When cross-compiling, these C Flags are located in the <code>toolchain.<architecture>.cmake</code> files located, by default, in <code>/opt/emac/5.X/</code>, with ''X'' being the specific version of SDK. The following table will give a brief overview of the different build types.


<br />
<br />
<table style="border-style:double; border-width:2px; margin-top:-10%; margin-bottom:-3%;"><tr style="border-style:double; border-width:2px;"><td>'''Name:'''</td><td>'''Type:'''</td><td>'''Debugging Features:'''</td><td>'''Description:'''</td><td>'''Optimization Level:'''</td><td>'''C Flags Used:'''</td></tr>


<tr style="border-style:solid; border-width:2px;"><td>Release</td><td>Release</td><td>disabled</td><td>Release targeted build optimized for best performance.</td><td>-O2</td><td>CMAKE_C_FLAGS_RELEASE</td></tr>


<tr style="border-style:solid; border-width:2px;"><td>MinSizeRel</td><td>Release</td><td>disabled</td><td>Release targeted build with experimental optimizations. (Builds using this should be thoroughly tested.)</td><td>-O3</td><td>CMAKE_C_FLAGS_MINSIZEREL</td></tr>


<tr style="border-style:solid; border-width:2px;"><td>Debug</td><td>Debug</td><td>enabled</td><td>A standard debugging oriented build, optimized for improved debugging.</td><td>-O0</td><td>CMAKE_C_FLAGS_DEBUG</td></tr>

</table>
<br />
<br />
<br />
If you wish to add any additional flags to a build type, they can be defined in the project's <code>CMakeList.txt</code> file as shown in the code snippet below.
<syntaxhighlight lang="cmake">
project(example)

SET(MAKE_C_FLAGS_DEBUG "${CMAKE_C_FLAGS_DEBUG} -Wall -Wpedantic")

# This will add the -Wall and -Wpedantic options to the existing debug build flags
</syntaxhighlight>
<!--{{warning | This is really useful information for any developer.  Knowing the level of optimization is insightful, so that should be included.  Knowing whether or not the build was stripped of debugging information is important if they ever intend to release binaries to the public (such as for updates) and to ensure small size and max speed.  Knowing what preprocessor defines are #def'd with a target is really useful when writing debugging code.


I would put all this in a table like the example I made above (but accurate and complete).  The border-radius and shadows will need to be overridden to make it look right.  Can always use css or a template for this.
}}-->


====Method 1: Create separate build directory====
To create a Release build using the 1st (recommended) method, use the following steps. This method is recommended because it allows both the Debug and the Release executable to exist at the same time.
<cl>
1. In a terminal, navigate to the base directory of the project.
* Create a new release build directory
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac | mkdir hello_emac-build-arm-release }}
* Change directories into the newly created directory.
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac | cd hello_emac-build-arm-release }} 
* Run <code>cmake</code> using the target architecture.
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac/hello_emac-build-arm | 1 = cmake .. -DARCH:STRING=arm -DCMAKE_BUILD_TYPE:STRING=Release }}{{note | The string 'MinSizeRel' can be used in place of 'Release' for a potentially smaller executable}}
* Compile the code using <code>make</code>.
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac/hello_emac-build-arm | make }} 
</cl>
<br />
====Method 2: Re-use build directory====
Another option for creating a release build is as follows:
<cl>
1. In a terminal, navigate to the build directory of the project.
* Clean the directory with <code>make</code>
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac/hello_emac-build-arm | 1 = make clean}}
* Run <code>cmake</code> using the target architecture.
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac/hello_emac-build-arm | 1 = cmake .. -DARCH:STRING=arm -DCMAKE_BUILD_TYPE:STRING=Release }}{{note | The string 'MinSizeRel' can be used in place of 'Release' for a potentially smaller executable}}
* Compile the code using <code>make</code>.
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac/hello_emac-build-arm | make }} 
</cl>

===Renaming the Target Executable===
To rename the executable, the <code>ADD_EXECUTABLE()</code> function arguments must be changed. The first argument refers to the name of the executable, and the second refers to the source code file.

To change the name of the executable from "main" to "new_name", change the <code>ADD_EXECUTABLE()</code> from the first code box to the second code box.
<syntaxhighlight lang="cmake">
ADD_EXECUTABLE(main main.cpp)
</syntaxhighlight>

<syntaxhighlight lang="cmake">
ADD_EXECUTABLE(new_name main.cpp)
</syntaxhighlight>

===Adding Include Files===
To add an include file and implementation file (in this case, the <code>tools.cpp</code> and <code>tools.h</code> in the <code>util</code> and <code>include</code> directory, respectively) to the CMake project, changes will need to be made to the CMakeLists.txt file. Please refer to the code sample below.

# The directory to be included must be specified by the <code>INCLUDE_DIRECTORIES()</code> function. The variable <code>${PROJECT_SOURCE_DIR}</code> refers to the base path of the project which is generally where this <code>README</code> file is located.
# The <code>SOURCES</code> must be set. This list of files should include all of the source files in the project.

<syntaxhighlight lang="cmake">
INCLUDE_DIRECTORIES(${PROJECT_SOURCE_DIR}include)

SET(SOURCES
     ${PROJECT_SOURCE_DIR}main.cpp
     ${PROJECT_SOURCE_DIR}util/tools.cpp
     )
SET(HEADERS
     ${PROJECT_SOURCE_DIR}include/tools.h
     )

ADD_EXECUTABLE(main ${SOURCES} ${HEADERS})
</syntaxhighlight>

<!-- /*********************************************************************************************************/ -->
<!-- /******************************************   More Information   *****************************************/ -->
<!-- /*********************************************************************************************************/ -->
{{:Templateimpl:moreinfo | initials=KY | title=Creating a New EMAC OE SDK Project with CMake | desc=Creating an EMAC OE SDK project for use with CMake | project=OE 5.0 }}
<!--{{:Templateimpl:whatnext | initials=KY | title=Creating a New EMAC OE SDK Project with CMake | desc=Creating an EMAC OE SDK project for use with CMake | project=OE 5.0 }}-->
* [[System_Log_In | System Log In]]
* [[Serial_Connections | Serial Connections ]]
* [[Network_Connections | Network Connections ]]
* [[System_Log_In | System Log In ]]
* [[Remote_Debugging_EMAC_OE_SDK_Projects_with_gdbserver | Remote Debugging EMAC OE SDK Projects with gdbserver ]]
* [[System_Logging | System Logging ]]