======= Getting Started with Yocto and C/C++ =======

This guide will go through setting up a build environment and building an x86_64 image, and adding a small "hello world" application to it. This page is a summary of the information from [[software:linux:yocto:setup|Setup and Building]], [[software:linux:yocto:recipes|Recipes]] and [[software:linux:yocto:devtool|devtool]].

===== Setting up the Build Environment =====

Create a directory in a suitable place to store everything related to this build.
This guide will assume everything is in a directory called ''yocto'' in your the home of the user ''ubuntu'': ''/home/ubuntu/yocto''. This folder can by anywhere on the system though.

Next, clone ''poky'', yocto's reference distribution. At the time of writing ''yocto-3.0.2'' is the newest release, feel free to substitute it for a newer/different version.
<code>
git clone -b kirkstone git://git.yoctoproject.org/poky
</code>

Next, create a build directory:
<code>
mkdir build
</code>

Now we can initialize yocto using:
<code>
. poky/oe-init-build-env build/
</code>
This will populate the build directory with all necessary files and give you access to ''bitbake'', the build system used by yocto.

==== Setting the Machine ====

Setting the machine tells bitbake what hardware to build for. This build will be a 64bit qemu image, so we can set the machine to ''qemu86-64''. This means we can run this image in Qemu.

Open ''local.conf''
<code>
nano conf/local.conf
</code>

and add this line to set the machine:
<code>
MACHINE = "qemux86-64"
</code>

The build environment is now set up.

===== Building an Image =====

You can now build an image. This command will build a minimal image provided by ''poky'':

<code>
bitbake core-image-minimal
</code>

Once the image is built, it can be run in qemu using

<code>
runqemu qemux86-64 nographic
</code>

''runqemu'' is a script that comes with bitbake, ''qemux86-64'' specifies the machine, and ''nographic'' tells qemu to run in the terminal rather than its own window. This is useful when building on a system with no graphical environment such as a container or when building in the cloud.

The default login is ''root'' with no password. You can use ''poweroff'' to shut down the virtual machine and exit qemu.

===== Creating a Hello World C++ Application =====

This section will show you how to create a hello world application in C++ with Cmake.

First, create a directory in your yocto folder. This will contain the application itself.
The location is arbitrary, and was chosen merely for convenience. It could be anywhere.
Assuming you are still in the ''build'' directory:

<code>
mkdir ../helloworld
</code>

Next, create a ''main.cpp'' in the new directory

<code>
cd ../helloworld
nano helloworld.cpp
</code>

with the following content:

<code>
#include<iostream>

int main()
{
        std::cout << "Hello World!\n";
        return 0;
}
</code>

Now create a ''CMakeLists.txt'' for cmake:

<code>
nano CMakeLists.txt
</code>

CMakeLists.txt
<code>
cmake_minimum_required(VERSION 3.5)

project(yocto-test LANGUAGES CXX)

add_executable(hello helloworld.cpp)

install(TARGETS hello DESTINATION bin)

</code>

==== Optional: Verifying that the Application Works ====

This is an optional step to verify the application itself is built correctly before adding it to the image.
Create a ''build'' directory inside the application folder for cmake to store its data in.
Then execute ''cmake'' inside that folder to create the build configuration and build the 
application by running ''make''.
Now there should be a ''hello'' executable that prints "hello world" when executed.
After confirming it works, change back to ''yocto/build'' before continuing with the next step.

<code>
mkdir build
cd build
cmake ..
make
./hello
cd ../../build
</code>

===== Creating a Recipe for the application =====

We use [[software:linux:yocto:devtool|devtool]] to create a new [[ .:recipes | Recipe ]] for our ''hello'' application.
<code>
devtool add ../helloworld/
</code>

This should finish with a message similar to this one:
<code>
INFO: Recipe /home/ubuntu/yocto/build/workspace/recipes/helloworld/helloworld.bb has been automatically created; further editing may be required to make it fully functional
</code>

This means devtool ran successfully and created a recipe at the specified location. 

To test whether this recipe works, build it by running bitbake:

<code>
bitbake helloworld
</code>

This should run without errors and print something like this when it's finished:

<code>
NOTE: Tasks Summary: Attempted 506 tasks of which 497 didn't need to be rerun and all succeeded.
</code>

This means the package provided by the recipe was built successfully.

===== Adding the Recipe to the Image =====

Now that we have a recipe, we need to add it to the image to test it out.
Adding packages to recipes is done in ''conf/local.conf'' by appending them to ''CORE_IMAGE_EXTRA_INSTALL'':

Edit ''local.conf''
<code>
nano conf/local.conf
</code>

and add the following:
<code>
CORE_IMAGE_EXTRA_INSTALL += "helloworld"
</code>

Rebuild the image
<code>
bitbake core-image-minimal
</code>

And run qemu

<code>
runqemu qemux86-64 nographic
</code>

Log in as ''root'' and you can now run our ''hello'' application:
<code>
root@qemux86-64:~# hello
Hello World!
</code>

Congratulations! You have now developed your own C++ application and added it to a yocto image.