Introduction
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.
Prerequisites
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.
Walkthrough
Step 1 - Load the .ebp
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
Open 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.
Select the HelloWorld target and click Duplicate.
You will be prompted to chose a name for the new target. In this case we’ll be using NoughtsAndCrosses.
The new target should then be appended to the target list.
The target will be created with the same settings as the HelloWorld target.
To avoid conflicts, those settings will have to be changed.
Change the Output filename: from .\build\hello.elf to .\build\NoughtsAndCrosses.elf, and then make sure that Examples\HelloWorld\main.cpp and 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 Examples\HelloWorld\main.cpp.
Step 3 - Set the build options
Open Project > Build options... (or alternatively press Alt+F7).
Search directories
Select the NoughtsAndCrosses build target.
Then select the Search directories tab.
You will see that the directory is set to Examples\HelloWorld.
Select the Examples\HelloWorld entry and click Edit.
You will be prompted to edit the directory.
You can simply manually rename it to Examples\NoughtsAndCrosses.
(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 ... button.)
When the directory is correct, press the Ok button.
(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 Yes.)
Double check that the directory is correct before moving on.
Post-build steps
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 .bin file.
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 .\build\hello.bin.
The hello parts of these names matches up with the hello.elf mentioned in the project properties.
(Note that none of these files (the .elf, the .hex or the .bin) have to match up with the build target name, hence the HelloWorld target uses hello.elf, hello.hex and hello.bin rather than HelloWorld.elf, HelloWorld.hex and HelloWorld.bin.)
In this case, for the .hex and .bin files to match up with the .elf file name,
these need to be changed to .\build\NoughtsAndCrosses.hex and .\build\NoughtsAndCrosses.bin.
However, there is in fact a way to make the .hex and .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
Like so:
The $(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 .elf name.
(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 .\build\NoughtsAndCrosses.elf to .\build\$(TARGET_NAME).elf.
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 Examples.
If you didn’t get the source files earlier, get them now by downloading them from Github by clicking Clone or download followed by Download ZIP.
(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 PokittoLib\Examples\NoughtsAndCrosses.
So navigate to PokittoLib\Examples and then create the folder NoughtsAndCrosses.
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 .h and .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 OK.
Next another box will appear, asking which build target you want to associate the files with.
By default all build targets are selected.
Choose Deselect All and then select the build target you recently created.
In this case that’s NoughtsAndCrosses.
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 F7.
You may be prompted with a box asking if you’d like to save changes before you start building. Choose Yes.
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 NoughtsAndCrosses.bin.
Simply upload the .bin file as you would any other .bin file.
