I’m going to be showing you how to add a new build target on EmBitz via the PokittoLib.
For demonstration purposes I will be using my noughts and crosses game because it is relatively small.
Firstly, make sure you have a copy of the PokittoLib downloaded and set up.
Secondly, make sure you have a copy of my Noughts And Crosses game.
Step 1 - Load the
First, open up PokittoEmBitz.ebp. This can be done in one of two ways:
- Drag PokittoEmBitz.ebp onto EmBitz.exe (or a shortcut to EmBitz.exe)
- Run EmBitz and then open it manually through the EmBitz UI
Step 2 - Create the build target
Project > Properties...
Go to the
Build targets tab. You will see a list of build targets and various options.
Rather than setting up a new build target from scratch, it is easiest to duplicate the
HelloWorld target and click
You will be prompted to chose a name for the new target. In this case we’ll be using
The new target should then be appended to the target list.
The target will be created with the same settings as the
To avoid conflicts, those settings will have to be changed.
Output filename: from
.\build\NoughtsAndCrosses.elf, and then make sure that
Examples\HelloWorld\My_settings.h are unticked in the
Build target files: area.
If you forget to untick those files, you will get errors when trying to compile because
main will be defined twice, once in
Examples\NoughtsAndCrosses\main.cpp and again in
Step 3 - Set the build options
Project > Build options... (or alternatively press
NoughtsAndCrosses build target.
Then select the
Search directories tab.
You will see that the directory is set to
Examples\HelloWorld entry and click
You will be prompted to edit the directory.
You can simply manually rename it to
(If you’ve already unpacked your files into the appropriate directory (as described later in the tutorial) you can select that directory by clicking on the
When the directory is correct, press the
(If you selected the directory manually then you may be asked if you would like to keep the path relative, in which case you should choose
Double check that the directory is correct before moving on.
Now select the
Pre/post build steps tab.
There shouldn’t be any
Pre-build steps, but the
Post-build steps should have two lines.
The first is the command for doing an object copy to turn the generated machine code into a
The second is the command for creating the cyclic redundancy check (CRC) checksum that certain ARM units need to verify the integrity of the code.
If you look carefully, you’ll notice that the post-build commands mention ‘hello’ three times.
One case of
.\build\hello.hex and two cases of
hello parts of these names matches up with the
hello.elf mentioned in the project properties.
(Note that none of these files (the
.hex or the
.bin) have to match up with the build target name, hence the
HelloWorld target uses
hello.bin rather than
In this case, for the
.bin files to match up with the
.elf file name,
these need to be changed to
However, there is in fact a way to make the
.bin files match the
.elf file exactly, so that if you change the
.elf name, you don’t need to edit the post-build step again.
Simply set the build event as:
arm-none-eabi-objcopy.exe -I ihex .\build\$(TARGET_OUTPUT_BASENAME).hex -O binary .\build\$(TARGET_OUTPUT_BASENAME).bin .\build\lpcrc .\build\$(TARGET_OUTPUT_BASENAME).bin
$(TARGET_OUTPUT_BASENAME) part is what’s known as a (expandable) compiler macro, or an (expandable) compiler variable.
It essentially acts as a stand in for a project-specific or target-specific value, similarly to a C++ macro, hence why the build event updates automatically to reflect the specified
(For a list of other compiler variables see here.)
Additionally, if you want to make the output files match the name of the target, you can change
Combining this with the aforementioned
$(TARGET_OUTPUT_BASENAME) in the build event means you can then use that target as a base for duplication for creating new build targets and then you will only have to change the target name and the target includes, you won’t have to touch the
.elf file or build events.
Step 4 - Add the source files
Next you need to put all the source files into a subdirectory in
If you didn’t get the source files earlier, get them now by downloading them from Github by clicking
Clone or download followed by
(In case you didn’t see it earlier, Noughts And Crosses can be found here.)
Following that, you need to make the subdirectory that you’re going to put your files in. That subdirectory should have the same name that you supplied as the search directory in step 3.
In this case that’s
So navigate to
PokittoLib\Examples and then create the folder
Then you need to open the zip file you downloaded earlier and copy the source files across to the newly created folder.
You don’t have to include non-source if you don’t want to, but it’s good practice to keep the licence around.
Go to the
Management pane on the left, right click on the
PokittoEmBitz project, and select
Add files recursively....
When the directory navigator appears, select the directory that you have put the source files in.
A box will pop up showing all the files in that directory.
Only ticked files will be included in the project.
EmBitz should automatically select all the
.cpp files for you,
which in most cases are the only files that you want to include in the project.
If you are happy with all the files that have been ticked, press
Next another box will appear, asking which build target you want to associate the files with.
By default all build targets are selected.
Deselect All and then select the build target you recently created.
In this case that’s
Step 5 - Building
(Most people should already know this, but I’m including this step for the sake of completeness.)
Now to confirm that everything works.
First, make sure your new build target is the selected build target.
In this case that means go to
Build > Select target > NoughtsAndCrosses
Then build the target by going to
Build > Build target or pressing
You may be prompted with a box asking if you’d like to save changes before you start building. Choose
Wait for the build to finish.
(If there is a “multiple declaration of ‘main’” error, see step 2 and recheck the project properties, if there is a different error, handle it.)
Then check the
PokittoLib\build directory and you should see the appropriate files have been generated, including a
Simply upload the
.bin file as you would any other