[Tutorial][Advanced]Adding a new build target to PokittoLib on EmBitz


#1

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.


EmBitz Errors when building
[Tutorial][Advanced]1.Programming Pokitto "offline" using EmBitz IDE
[Demo]Sketchi
#2

@Pharap, i had a little struggle placing the game files. Was it your intension to place them inside the example folder ?

Did get it working, now moving files from mbed to embitz. Next step i am going to check if i can compile the new code with the C++11 features. (if that was the problem)


#3

Yes.

Truthfully I haven’t quite got round to figuring out if it’s possible to place them in other folders. I decided to play it safe and place them in the ‘Examples’ folder for now.

I know it is possible to put them elsewhere, but it’s a question of whether any extra settings would need changing.
At minimum it would probably be another step in the tutorial.

When you do, summon me on the other thread, since that’s a separate issue to adding build targets.
(I don’t want to go off on a tangent on a tutorial thread.)


#4

That is not mentioned in the tutorial, would really help to add it.

Maybe like this :

And place it inside the examples folder, this is found inside the PokittoLib.


#5

I do mention adding them at the start of Step 4:

Should I change Examples\NoughtsAndCrosses to PokittoLib\Examples\NoughtsAndCrosses?
Is there something else I could do to make it clearer?


#6

I read it like i had to add those files into embitz using the “add recursivly function”.

So i did not even see you had a image of the folder in the first step, i just moved along to adding them in embitz directly

To me as i was reading it, it was not clear i had to get the files out of the download folder and place them into the pokittolib under examples.

maybe the first line of step 4 should be more like :

Next you need to place the downloaded NoughtsAndCrosses folder into the examples folder of the PokittoLib
(That subdirectory should have the same name that you supplied as the search directory in step 3).
In this case that’s Examples\NoughtsAndCrosses. Simply copy and paste them into the folder.

Hope i am being clear here, if not please say.


#7

Hrm, I’ll look into adding another step that shows the folder creation and the moving of the files.
I’ll probably add it tomorrow rather than today though.


#8

I’ve made some edits to step 4.
Do you think it’s clear enough now?


#9

Tottaly clear :+1:


#10

I’ve recently discovered a way to make the post-build event dependent on the name of the .elf file so it can be changed in Project > Properties... and then the buid event will almost automatically update.

‘Almost’ because it seems the project build options don’t automatically update when the project/target options are changed, so you have to open the build options window and ‘OK’ it for the changes to apply.

Essentially you replace the post-build event with:

arm-none-eabi-objcopy.exe -I ihex .\build\$(HelloWorld_OUTPUT_BASENAME).hex -O binary .\build\$(HelloWorld_OUTPUT_BASENAME).bin
.\build\lpcrc .\build\$(HelloWorld_OUTPUT_BASENAME).bin

Where HelloWorld is the name of the build target (e.g. NoughtsAndCrosses or Pixonia).

To go a step further, you can then replace the build target’s output filename with build\$(TARGET_NAME).elf and the output files will take on the name of the build target.

For example, the Sprites build target would generate Sprites.elf and thus Sprites.bin instead of clipped.elf and clipped.bin as it currently is.

I won’t update the tutorial yet in case I find a better way of doing this or figure out why the update doesn’t automatically probagate, but this is really useful.

If we changed all the examples to use this technique (or at least HelloWorld), then the build target could be copied without having to change the post-build event or the output filename, thus allowing the user to skip a chunk of this tutorial.


Edit:

It seems that while $(HelloWorld_OUTPUT_BASENAME) is lagged, $(TARGET_OUTPUT_BASENAME) is not.
Thus the post build script can be safely replaced with:

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

For all targets.


Edit2:

I have added the new information.


#11

As of this PR there is now a new “BaseTarget” build target that features the relocatable build target settings.

For now, here’s a summary of the difference:

The old method was:

  • Duplicate a target
  • Rename the duplicate
  • Rename the .elf file
  • Remove the additional file references
  • Adjust the target search directory
  • Adjust the post-build script
  • Include and associate the relevant files

The new method is:

  • Duplicate the BaseTarget target
  • Rename the duplicate
  • Adjust the target search directory
  • Include and associate the relevant files

Or, to put it another way, if you use a version of the PokittoLib that features the new “BaseTarget” and you use that as the base for your duplication then you do not have to:

  • Rename the .elf file
  • Remove the additional file references
  • Adjust the post-build script

At some point I will either edit the revised steps into this tutorial or create a new tutorial.

To help me decide I’m going to leave a poll here with the hopes that I’ll get a few replies to help me decide.
After all, I am doing this all for the benefit of others, so it makes sense to ask others which approach will work best.

  • Edit this tutorial with the new steps and cut out all the extra info
  • Make a new tutorial for the simpler method and keep this one to demonstrate the ‘longer’ method

0 voters