SimulIDE Knowledge Base
– COMPILERS –
SimulIDE does not distribute any compiler.
To use a compiler it must be installed in your system and working properly.
Then SimulIDE can use it by executing it's command and arguments.
This is achieved by configuring the compiler command and options in XML files located at SimulIDE/data/codeeditor/compilers/ or User_data_folder/codeeditor/compilers/
There are some compilers already configured included in SimulIDE, but you might need to tweak some settings within the XML file according to your compiler's specifications (e.g., altering the executable name or extension for Windows).
See File Structure below to know how these files work and how to edit them or add new compilers.
If you have any questions please ask in our forum
Some compilers are automatically loaded for some file extensions, for example:
.ino : Arduino compiler.
.gcb: GcBasic compiler.
.as : Script compiler.
If your file has a different extension, you need to choose a compiler for that file or create a new one.
Settings:
In version 1.0.0, open "Compiler Settings" in the tool bar by selecting it from the !
Settings menu and choose a compiler from the list.
In version 1.1.0 first choose a compiler in "File Settings" then configure the compiler in "Compiler Settings".
Once there, customize any options (like 'Tool Path') if necessary.
!
Options can be different for each compiler and will be added depending on the fields used in the configuration file.
Compiling:
Once the compiler is configured you can compile the file by clicking in the compile button in the tool bar: !
Have a look at the bottom panel to see the output of the compiling process and check if there is some error.
If there are no errors you can upload the hex file generated to a microcontroller in the circuit by clicking the upload button in tool bar: !
If you click the upload button it will compile first and then upload.
Important!!
Note that if there is more than one microcontroller in the circuit, the hex file will be uploaded to the "active" microcontroller, which is the one with a yellow dot:
!
To change the "active" microcontroller, right-click on it to open context menu and select "Main Mcu"
Adding Compilers:
SimulIDE drives external compilers/assemblers through small XML definition files. Each file describes a compiler: the tool to launch, the arguments to pass, and how the firmware file is produced. This guide explains how to create your own compiler definitions.
Where to put your compiler files
SimulIDE looks for compiler definitions in two places:
- User data folder: codeeditor/compilers/compilers for high-level toolchains and codeeditor/compilers/assemblers for assemblers. Definitions placed here override the built-in ones with the same name.
- SimulIDE folder: data/codeeditor/compilers/compilers and .../assemblers (bundled with the installation).
Your user data folder location depends on your system/configuration. Compiler definitions in the user data folder are always loaded first, so you can add new compilers by simply dropping a .xml file into <userData>/codeeditor/compilers/compilers (or assemblers) without touching the installation.
Every compiler name and assembler name appears in the Compiler dropdown of the file properties dialog, so new definitions become selectable for any file as soon as SimulIDE starts.
File structure:
The structure of the xml file is like this:
<compiler name="anyName" type="xx" buildPath="somePath" syntax="f.syntax" >
<step
command="executable"
arguments=" arguments for executable"
argsDebug=" arguments for executable in debug mode"
/>
<step
command="executable2"
arguments=" arguments for executable2"
argsDebug=" arguments for executable2 in debug mode"
/>
</compiler>
First the compiler name, type and other characteristics are defined in the field "compiler".
Then you can add as many build steps as you want in fields "step".
Field "compiler":
<compiler name="anyName" type="anyType" buildPath="somePath" syntax="syntaxFile" >
|
Attribute |
Required |
Description |
|
name |
Yes |
Name shown in the Compiler dropdown. Must be unique among compilers and assemblers. |
|
type |
Yes |
Defines the toolchain class and, for assemblers, the list file format (see below). |
|
syntax |
No |
Syntax highlighting file. If omitted, the current syntax is kept. |
|
buildPath |
No |
Directory (relative to the open file) where build outputs go. Created automatically if it doesn't exist. |
|
inclPath |
No |
Default include path passed to the -I option of many assemblers. |
|
uploadhex |
No |
Search for fileName.hex to upload. |
type: can define certain characteristics of the debugger.
You can encode some characteristics in 2 numbers at the end, for example when type="myType01"
The key is in the last 2 numeric digits: "01".
From left to right:
First digit "0*" language level:
Value can be 0 or 1: 0 for asm, 1 for high level
Second digit "*1" lst file type:
Value can be from 0 to 3:
- Bit 0: use ":" ?
0 doesn't use ":" (gpasm ).
1 uses ":" (avra, gavrasm) - Bit 1: position of flash address (0 or 1)
buildPath: folder to be used as build path by the compiler.
You can use "substitutions", for example if the source file is myfile.c
And you define buildPath like this: buildPath="build_$fileName"
Then a folder with name build_myfile will be created and used as build path.
Note that you must use this path in your command arguments if needed (see example below).
syntax: syntax file used for highlighting.
Syntax files are located at: SimulIDE_1.x.x/data/codeeditor/syntax/
You can add your custom syntax files in that folder and use in your compiler definitions.
uploadhex search for fileName.hex to upload. Set to uploadhex="false" for tools that don't produce a hex file (e.g. tools that output only a .lst/.bin).
Compiling or Debugging will not upload any firmware to the MCU in ciruit. Otherwise SimulIDE will search for fileName.hex to upload.
Build steps:
You can add as many build steps as you want.
Each step need to have at least a "command".
<step
command="executable"
arguments=" arguments for executable"
argsDebug=" arguments for executable in debug mode"
/>
Each step runs one command line, in order. Steps run sequentially; if a step fails (returns an error), the build stops and following steps are not executed. This lets you chain, for example, a compile step followed by an objcopy step.
|
Attribute |
Required |
Description |
|
command |
Yes |
The executable to run (see "Tool Path" below for how its location is resolved). |
|
arguments |
No |
The command line arguments. Supports substitution tokens. |
|
argsDebug |
No |
Alternative arguments used when compiling for debugging (Debug button). If omitted, the same arguments are used. |
Note: argsDebug must contain all the substitutions you want to work in debug mode. It does not inherit from arguments.
Substitutions:
You can use some substitutions in your command arguments and other values.
For example $FilePath will be replaced with the actual path to the source file.
Let's say we have this source file: /home/user/myfile.asm
Then we can use these substitutions:
|
Wildcard |
Example |
Replaced with |
|
$filePath |
/home/user/myfile.asm |
complete file path |
|
$fileDir |
/home/user/ |
path to file folder |
|
$fileName |
myfile |
file name (without extension) |
|
$fileExt |
.asm |
file extension (with dot) |
|
$buildPath |
- |
build path (defined in xml file) |
|
$inclPath |
- |
include path (defined in Settings Dialog) |
|
$family |
- |
device family (defined in Settings Dialog) |
|
$device |
- |
device model (defined i Settings Dialog) |
Settings shown to the user
Which settings appear in the Compiler Settings dialog depends on the tokens you use:
- Include $inclPath in any step → an Include Path setting appears.
- Include $extraArgs → an Extra Build Arguments setting appears.
- Include $device → a Device setting appears.
- Include $family → a Family setting appears.
The Tool Path setting always appears; it is prepended to every command. Users can type there the full path to the folder where the executables live (e.g. the bin folder of a toolchain) or leave it empty when the tools are already in the system PATH.
Example:
This is a simplified version of the xml file for Avr gcc compiler:
<compiler name="Avrgcc" type="avrgcc" buildPath="build_$fileName" useDevice="true">
<step
command="avr-gcc"
arguments=" -mmcu=$device -Os -o $buildPath$fileName.elf $filePath"
argsDebug=" -mmcu=$device -Og -o $buildPath$fileName.elf $filePath"
/>
<step
command="avr-objcopy"
arguments=" ihex $buildPath$fileName.elf $buildPath$fileName.hex"
/>
<compiler/>
Let's say that we are compiling a file with path: /path/toMyproject/mycode.c
And we have these settings for the compiler:
Tool Path: /path/to/myCompiler/
Device: atmega8
It will do these substitutions for the first build step:
buildPath="build_$fileName" is changed to: buildPath="/path/toMyproject/build_mycode"
-mmcu=$device is changed to: -mmcu=atmega8
$buildPath is changed to: /path/toMyproject/build_mycode/
$fileName is changed to: mycode
So $buildPath$fileName.elf becomes: /path/toMyproject/build_mycode/mycode.elf
$filePath is changed to: /path/toMyproject/mycode.c
In this case, because we indicated a buildPath, it will automatically create the build folder:
/path/toMyproject/build_mycode
And the complete command it will execute for the first build step is this (all in one line):
"/path/to/myCompiler/avr-gcc" -mmcu=atmega8 -Os -o /path/toMyproject/build_mycode/mycode.elf "/path/toMyproject/mycode.c"
Tips
- Test your definition with a very small source file and watch the output in the Compile Output panel: the exact command line that is launched is printed there, which helps debug argument problems.
- Verify your arguments by running the printed command manually in a terminal from the source file's folder.
- If marking errors in the editor matters to you, the tool should print error lines containing the source file name followed by a line number; SimulIDE will use the first number found in matching lines to point at the error.
- Keep the name unique — the first definition loaded wins when the same name exists in both the user data folder and the install folder.