Difference between revisions of "Creating a New EMAC OE SDK Project with CMake"

From wiki.emacinc.com
Jump to: navigation, search
m (Reviewed, made various changes/fixes, and added notes for later.)
Line 1: Line 1:
{{todo| Review (08.07.2015-12:59->KY+)(08.17.2015-12:07->KY+)(08.17.2015-14:25->KY+)|Klint Youngmeyer| project=OE 5.0,KY }}
+
{{todo| Buggy (08.07.2015-12:59->KY+)(08.17.2015-12:07->KY+)(08.17.2015-14:25->KY+)(08.17.2015-17:40->MD-)|Klint Youngmeyer| project=OE 5.0,KY,MD }}
 
{{#seo:
 
{{#seo:
 
|title=Creating a New EMAC OE SDK Project with CMake
 
|title=Creating a New EMAC OE SDK Project with CMake
 
|titlemode=append
 
|titlemode=append
|keywords=EMAC, OE5, CMake, include, library, compile
+
|keywords=CMakeLists.txt, CMake cross-compiling, CMake, CMake ARM, oe_init_project
|description=Creating an EMAC OE SDK project for use with CMake
+
|description=Creating an EMAC OE SDK project which uses the CMake build system.
 
}}
 
}}
  
Line 10: Line 10:
 
<!-- /****************************************  Page Description Text  ****************************************/ -->
 
<!-- /****************************************  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 compiling a new project with CMake and running it on the target machine.
+
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__
 
__TOC__
Line 17: Line 17:
 
<!-- /*****************************************  General Information  *****************************************/ -->
 
<!-- /*****************************************  General Information  *****************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
{{:Templateimpl:geninfo | 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: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 <code>emac-tools-projects</code> apt package, which is part of the EMAC SDK. For instructions on installing the EMAC SDK, please see [[Getting_Started_with_the_EMAC_OE_SDK#Installing_EMAC_SDK |this]] section in the getting started guide.
 
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 <code>emac-tools-projects</code> apt package, which is part of the EMAC SDK. For instructions on installing the EMAC SDK, please see [[Getting_Started_with_the_EMAC_OE_SDK#Installing_EMAC_SDK |this]] section in the getting started guide.
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*****************************************  Using/Working With  ******************************************/ -->
 
<!-- /*****************************************  Using/Working With  ******************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
{{:Templateimpl:using | 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: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 to generate CMake files automatically for a project. When using the EMAC SDK there are currently two options for cross compiling:
+
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:
* arm
+
* <code>arm</code>
* x86
+
* <code>x86</code>
 
For the purposes of this guide, the <tt>arm</tt> option will be used for the listed examples.
 
For the purposes of this guide, the <tt>arm</tt> option will be used for the listed examples.
 
=== Host Machine Compiling ===
 
=== Host Machine Compiling ===
Navigate to the directory where the project will be located. Then run the CMake new project script.
+
Navigate to the directory where the project will be located. Then run the CMake new project tool, <code>oe_init_project</code>.
 
{{clo}}
 
{{clo}}
 
{{clio | username=developer | hostname=ldc | pwd=~/projects | oe_init_project -n hello.c }}
 
{{clio | username=developer | hostname=ldc | pwd=~/projects | oe_init_project -n hello.c }}
Line 78: Line 78:
 
* Desktop Build Directory (''hello_emac-build'' in this case)
 
* Desktop Build Directory (''hello_emac-build'' in this case)
  
The ''CMakeLists.txt'' contains the required information to automatically create a ''Makefile'' for a given architecture.  This was created by the EMAC <tt>oe_init_project</tt> script, and will need to be modified over time as a project grows.  The comments in the 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 your project grows.  The CMake project provides extensive documentation on how to work with these files.
+
Despite what the file extension implies, the ''CMakeLists.txt'' is actually a script which contains the required information to automatically create a ''Makefile'' for any supported architecture.  This file was generated by the EMAC <tt>oe_init_project</tt> tool, and will need to be modified over time as a project grows.  The comments in the ''CMakeLists.txt'' 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 CMake project provides extensive documentation on how to work with these files.
  
The source code file generated by the script (''hello.c'') contains a basic Hello World style program.
+
The source code file generated by the script (''hello.c'') contains a basic Hello World style program.  This can provide a starting point for your application, or be replaced by another source file with the same name.
  
The ''README'' file contains more information on using ''CMake'' with the EMAC 5.0 SDK.
+
The ''README'' file contains more information on using ''CMake'' with the EMAC 5.0 SDK.  You may refer to this file for quick reference.
  
The Desktop Build Directory (''hello_emac-build'') contains the executable ''hello_emac'', the ''Makefile'', and various cache files.  These were automatically created by CMake and by the build system, and can be recreated at any time.
+
The Desktop Build Directory (''hello_emac-build'') contains the executable, ''hello_emac'', the ''Makefile'', 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 devices drivers or the touchscreen (if so equipped).
 
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 devices drivers or the touchscreen (if so equipped).
 +
 +
{{warning | How to set up a project so that the user may build both a desktop and a target version simultaneously should be described, for cases where both exist.  For example, the md5 tool I'm working on now is just such a project.  The desktop tool will add a few features which won't be in the board-only tool, so the build system will have to set #defines I'll be able to use to selectively compile portions of the code. }}
  
 
Use the following steps to cross-compile the project and send it to a target board.
 
Use the following steps to cross-compile the project and send it to a target board.
 
<br />
 
<br />
 
<cl>
 
<cl>
1. In a terminal, navigate to the base directory of the project.
+
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 <tt>x86</tt>, then you will need to change all occurrences of <tt>arm</tt> in the following sections below to <tt>x86</tt>.}}
{{note | If the target board being used is <tt>x86</tt>, then change all occurrences of <tt>arm</tt> in the following sections below to <tt>x86</tt>.}}
 
 
* Create a build directory for cross compiling.  
 
* Create a build directory for cross compiling.  
 
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac | mkdir hello_emac-build-arm }}  
 
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac | mkdir hello_emac-build-arm }}  
 
* Change directories into the newly created directory.
 
* Change directories into the newly created directory.
 
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac | cd hello_emac-build-arm }}  
 
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac | cd hello_emac-build-arm }}  
* Run cmake using the target architecture.
+
* Run <tt>cmake</tt> using the target architecture.
 
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac/hello_emac-build-arm | 1 = cmake .. -DARCH:STRING=arm }}  
 
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac/hello_emac-build-arm | 1 = cmake .. -DARCH:STRING=arm }}  
* Compile the code using make.
+
* Compile the code using <tt>make</tt>.
 
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac/hello_emac-build-arm | make }}  
 
{{cli | username=developer | hostname=ldc | pwd=~/projects/hello_emac/hello_emac-build-arm | make }}  
  
Line 115: Line 116:
 
===Adding Include Files===
 
===Adding Include Files===
 
To add an include file (in this case, the <code>tools.cpp</code> and <code>tools.h</code> in the <code>include</code> directory) to the cmake project, changes will need to be made to the CMakeLists.txt file. Please refer to the code sample below.
 
To add an include file (in this case, the <code>tools.cpp</code> and <code>tools.h</code> in the <code>include</code> directory) 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 INCLUDE_DIRECTORIES() function. The variable ${PROJECT_SOURCE_DIR} refers to the base path of the project, generally where this README is located.
+
 
# The SOURCES must be set. This list of files should include all of the source files in the project.
+
{{warning|The formatting for filenames varies throughout this document.  Here, you used the <tt>code</tt> tag to format them, whereas earlier you used italics for filenames.  I think we're going to need templates for formatting filenames and directory names before we write more, so that these will be consistent across all of our documentation.  This page will need to be updated with them when they're ready.}}
 +
 
 +
# 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 <tt>README</tt> 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">
 
<syntaxhighlight lang="cmake">
Line 129: Line 133:
  
 
===Adding External Library Files===
 
===Adding External Library Files===
To add an external library to the cmake project, more changes will need to be made to the CMakeLists.txt file. Please refer to the code sample below. In this example, the ImageMagick library will be linked.
+
To add an external library to the CMake project, more changes will need to be made to the <tt>CMakeLists.txt</tt> file. Please refer to the code sample below. In this example, the ''ImageMagick'' library will be linked into the project.
#The library directory must be included using the INCLUDE_DIRECTORIES() function. This function must be before the ADD_EXECUTABLE() function.
+
#The library directory must be included using the <code>INCLUDE_DIRECTORIES()</code> function. This function must be before the <code>ADD_EXECUTABLE()</code> function.
#Use the TARGET_LINK_LIBRARIES() function to link the desired library to the target binary. This function must be after the ADD_EXECUTABLE() function.
+
#Use the <code>TARGET_LINK_LIBRARIES()</code> function to link the desired library to the target binary. This function must be after the <code>ADD_EXECUTABLE()</code> function.
  
 
<syntaxhighlight lang="cmake">
 
<syntaxhighlight lang="cmake">
 
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_BINARY_DIR} "/usr/include/ImageMagick")
 
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_BINARY_DIR} "/usr/include/ImageMagick")
 
  
 
ADD_EXECUTABLE(main main.cpp) # This should be here by default
 
ADD_EXECUTABLE(main main.cpp) # This should be here by default
 
  
 
TARGET_LINK_LIBRARIES(main MagickWand)
 
TARGET_LINK_LIBRARIES(main MagickWand)
Line 144: Line 146:
  
 
===Renaming the Target Executable===
 
===Renaming the Target Executable===
To rename the executable, the ADD_EXECUTABLE() 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 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 ADD_EXECUTABLE() from the first code box to the second ode box.
+
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">
 
<syntaxhighlight lang="cmake">
 
ADD_EXECUTABLE(main main.cpp)
 
ADD_EXECUTABLE(main main.cpp)
Line 156: Line 158:
  
 
===Adding Additional C/C++ Sourrce Files as Libraries===
 
===Adding Additional C/C++ Sourrce Files as Libraries===
Adding additional source file is accomplished similarly to adding external library files. See [[#Adding_External_Library_Files | above]].
+
Adding additional source files is accomplished similarly to adding external library files. See [[#Adding_External_Library_Files | above]].
# All included files must be included in the SOURCES list.
+
# All included files must be included in the <code>SOURCES</code> list.
# All header files must be included in the HEADER_FILES list.
+
# All header files must be included in the <code>HEADER_FILES</code> list.
 
# Each C/C++ source file must be added as a library before adding the executable.
 
# Each C/C++ source file must be added as a library before adding the executable.
# Add the executable, including the ${HEADER_FILES}.
+
# Add the executable, including the <code>${HEADER_FILES}</code>.
 
# Link the target libraries to the executable.
 
# Link the target libraries to the executable.
  
Line 193: Line 195:
 
* [[System_Log_In | System Log In]]
 
* [[System_Log_In | System Log In]]
 
* [[Serial_Connections | Serial Connections ]]
 
* [[Serial_Connections | Serial Connections ]]
* [[Network_Connections | Network_Connections ]]
+
* [[Network_Connections | Network Connections ]]
 
* [[System_Log_In | System Log In ]]
 
* [[System_Log_In | System Log In ]]
 
* [[Remote_Debugging_EMAC_OE_SDK_Projects_with_gdbserver | Remote Debugging EMAC OE SDK Projects with gdbserver ]]
 
* [[Remote_Debugging_EMAC_OE_SDK_Projects_with_gdbserver | Remote Debugging EMAC OE SDK Projects with gdbserver ]]
 
* [[CMake | CMake ]]
 
* [[CMake | CMake ]]
 
* [[System_Logging | System Logging ]]
 
* [[System_Logging | System Logging ]]

Revision as of 17:42, 17 August 2015

TODO: {{#todo: Buggy (08.07.2015-12:59->KY+)(08.17.2015-12:07->KY+)(08.17.2015-14:25->KY+)(08.17.2015-17:40->MD-)|Klint Youngmeyer|OE 5.0,KY,MD}}

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.

General Information

Creating a new EMAC CMake project is accomplished with the use of the oe_init_project program. This program is included in the emac-tools-projects apt package, which is part of the EMAC SDK. For instructions on installing the EMAC SDK, please see this section in the getting started guide.

Creating a New EMAC OE SDK Project with CMake

This section demonstrates how to use the EMAC CMake tool, oe_init_project, to generate CMake files automatically for a project. When using the EMAC SDK there are currently two options for cross compiling:

  • arm
  • x86

For the purposes of this guide, the arm 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, oe_init_project.

developer@ldc:~/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

-- Creating new project directory...
-- Creating new source file...
-- Building custom CMakeLists.txt file...
-- Done.

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

-- Creating build directory...

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

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

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

Scanning dependencies of target hello_emac
[100%] Building C object CMakeFiles/hello_emac.dir/hello.c.o
Linking C executable hello_emac
[100%] Built target hello_emac

The executable, in this case, is now inside the hello_emac/hello_emac-build directory.

Target Machine Compiling

The CMake project script has now made a project directory that contains the following:

  • CMakeLists.txt
  • Source code file (hello.c in this case)
  • README file
  • Desktop Build Directory (hello_emac-build in this case)

Despite what the file extension implies, the CMakeLists.txt is actually a script which contains the required information to automatically create a Makefile for any supported architecture. This file was generated by the EMAC oe_init_project tool, and will need to be modified over time as a project grows. The comments in the CMakeLists.txt 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 CMake project provides extensive documentation on how to work with these files.

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

The README file contains more information on using CMake with the EMAC 5.0 SDK. You may refer to this file for quick reference.

The Desktop Build Directory (hello_emac-build) contains the executable, hello_emac, the Makefile, 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 devices drivers or the touchscreen (if so equipped).



WARNING!
How to set up a project so that the user may build both a desktop and a target version simultaneously should be described, for cases where both exist. For example, the md5 tool I'm working on now is just such a project. The desktop tool will add a few features which won't be in the board-only tool, so the build system will have to set #defines I'll be able to use to selectively compile portions of the code.


Use the following steps to cross-compile the project and send it to a target board.

  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 x86, then you will need to change all occurrences of arm in the following sections below to x86.
  2. Create a build directory for cross compiling.

    developer@ldc:~/projects/hello_emac# mkdir hello_emac-build-arm
  3. Change directories into the newly created directory.

    developer@ldc:~/projects/hello_emac# cd hello_emac-build-arm
  4. Run cmake using the target architecture.

    developer@ldc:~/projects/hello_emac/hello_emac-build-arm# cmake .. -DARCH:STRING=arm
  5. Compile the code using make.

    developer@ldc:~/projects/hello_emac/hello_emac-build-arm# make

    The make command creates the target executable in the hello_emac-build-arm directory.

  6. Now copy the executable to the target board. For information on copying the executable file, see the Transferring Files section.



For other ways to generate the CMake files, visit the CMake page.

Examples

This section will illustrate how to complete various different tasks associated with building a CMake project.

Adding Include Files

To add an include file (in this case, the tools.cpp and tools.h in the include directory) to the cmake project, changes will need to be made to the CMakeLists.txt file. Please refer to the code sample below.



WARNING!
The formatting for filenames varies throughout this document. Here, you used the code tag to format them, whereas earlier you used italics for filenames. I think we're going to need templates for formatting filenames and directory names before we write more, so that these will be consistent across all of our documentation. This page will need to be updated with them when they're ready.


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

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

Adding External Library Files

To add an external library to the CMake project, more changes will need to be made to the CMakeLists.txt file. Please refer to the code sample below. In this example, the ImageMagick library will be linked into the project.

  1. The library directory must be included using the INCLUDE_DIRECTORIES() function. This function must be before the ADD_EXECUTABLE() function.
  2. Use the TARGET_LINK_LIBRARIES() function to link the desired library to the target binary. This function must be after the ADD_EXECUTABLE() function.
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_BINARY_DIR} "/usr/include/ImageMagick")

ADD_EXECUTABLE(main main.cpp) # This should be here by default

TARGET_LINK_LIBRARIES(main MagickWand)

Renaming the Target Executable

To rename the executable, the ADD_EXECUTABLE() 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 ADD_EXECUTABLE() from the first code box to the second code box.

ADD_EXECUTABLE(main main.cpp)
ADD_EXECUTABLE(new_name main.cpp)

Adding Additional C/C++ Sourrce Files as Libraries

Adding additional source files is accomplished similarly to adding external library files. See above.

  1. All included files must be included in the SOURCES list.
  2. All header files must be included in the HEADER_FILES list.
  3. Each C/C++ source file must be added as a library before adding the executable.
  4. Add the executable, including the ${HEADER_FILES}.
  5. Link the target libraries to the executable.
SET(SOURCES 
    ${PROJECT_SOURCE_DIR}/include/tools.cpp
    ${PROJECT_SOURCE_DIR}/include/funcs.cpp 
    ${PROJECT_SOURCE_DIR}/include/tools.h
    ${PROJECT_SOURCE_DIR}/include/funcs.h
    )


SET(HEADER_FILES
    ${PROJECT_SOURCE_DIR}/include/tools.h
    ${PROJECT_SOURCE_DIR}/include/funcs.h
    )


ADD_LIBRARY(tools include/tools.cpp ${HEADER_FILES})
ADD_LIBRARY(funcs include/funcs.cpp ${HEADER_FILES})
ADD_EXECUTABLE(main main.cpp ${HEADER_FILES})


TARGET_LINK_LIBRARIES(main tools funcs)


Pages with Related Content