THE
PARTICLE COMPUTER DOCU
(Using SDCC on Windows)
This chapter summarises and explains how to use the
SDCC on Windows platforms.
Contents
Installing SDCC
Download our
installer package
.
Run the installer
The package contains
Obtaining the Particle Base System
Download the Particle Base System Snapshot. You can also obtain the sources from SVN.
(Ask your local guru)
If you download the snapshot, we recommend for the first time:
- Create a new folder C:\projects
- Save the tar file to C:\projects
- Start a MSYS shell by clicking the MSYS icon on your desktop or quick launch
bar
- At the prompt, type:
$ cd c:\projects
$ tar xzf ParticleBaseSystem.tar.gz
$ cd ParticleBaseSystem
Now you have the new subfolders demo and particle. particle
contains the stack and driver sources, demo contains a small demo program.
Compiling a project
Compiling the demo program
We assume you want to compile the demo program and already followed the instructions above.
If you renamed your folder and/or your program
sources, you have to modify the Makefile in build subfolder.
Run the following commands in your MSYS shell: (assuming you are still
in the same directory as above)
$ cd demo/build
$ make
Then the project will be build. You will find the demo.hex in your current
folder (MinGW: /c/projects/ParticleBaseSystem/demo/build, Windows:
C:\projects\ParticleBaseSystem\demo\build).
Compiling your own project
To compile your project with the make tool you have to adapt the
Makefile found in the build folder of the demo program with
a text editor that supports UNIX line breaks.
Change the following items:
- MAIN:
- set the path to your program source (relative or absolute path, seen from
your projects directory)
- MY_SRC:
- add other .c sources that your program needs, separated
by spaces (relative or absolute paths)
- PPATH:
- set the path to the particle base system folder
- BOARD:
- set your board version
- SENSORBOARD:
- set your sensorboard or leave blank if you do not want it
- STACKOPTIONS:
- enable the options that affect the stack like SDJS or ACK
- OPTIONS:
- enable the optional parts that do not affect the stack like RTC
Run the command $ make
in the build directory to compile
your project.
If you want to build the separate flash loader, enter $ make loader
If you want to remove the generated binary files, assembler files and dependency information
(.d files), enter $ make clean
File structure and concepts
Organization
The Particle Base System has the following file structure:
-
particle
- boards: contains processor and board related sources
- sensors: contains sensor drivers
- system: contains the RF stack, otap functions, rtc support etc.
- libtools: contains various helper functions
-
particle.mk: Makefile to build the system, must be included by the user's
Makefile
-
[project directory]
- build: contains the application Makefile and all binaries and
dependency files
Concepts behind the structure
The sources and dependencies follow the following principles:
- .c files are not included (except flash loader)
- only required header files are included
- header files of other sources are normally included in the .c files
- the header files only consist of preprocessor macros, function prototypes and variable
declarations (not definitions)
- header files do only contain the prototypes, macros and variables that are
required by others
- files like coreboard.h and sensorboard.h provide a certain level
of abstraction to simplify the development for more than one board version.
- all functions with parameters use the wparam pragma or attribute to increase
speed; they must not be called by function pointers or have to be modified
- no binaries together with sources
- the particle.mk Makefile contains all information about the available
boards, sensors and options. Board, sensorboard and options are set in the
application's Makefile, so particle.mk can normally remain untouched
The modularized Particle Base System does not need to reside in the project tree like the earlier versions. Also all binaries are located only in the build directory of the project so it is easy to "clean" from generated binaries. This enables the developer to handle base system and application separate.
You can also find two VCG files in the ParticleBaseSystem/particle/doc directory that display the dependencies. (requires xvcg or AISee)
Using MinGW and MSYS
MinGW and MSYS enriches and extens a Windows environment with many powerful GNU tools and allows us to run the SDCC which was designed on UNIX/LINUX systems by emulating such an environment.
MSYS shell vs. cmd.exe shell
There are some differences between the MSYS shell and the build-in cmd shell from Microsoft:
- Beside the DOS typical paths like C:\WINDOWS MSYS uses the UNIX style paths (like
/c/windows), too. The drives can be accessed via /[driveletter]/, the directory
separator is a "forward slash" / compared to the "backslash" \ Windows
uses.
- The [Tab] completion has a different behaviour: While Windows cycles through the
possible names depending on the prefix, MSYS shell stops after the longest matching common prefix
and waits for the next letter. Pressing [Tab] twice shows all possibilities depending on the
given prefix.
Example: Given two directories called projectsys and projectapp.
Windows shell:
C:\>cd pro
[Tab]
C:\>cd projectapp
[Tab]
C:\>cd projectsys
MSYS:
$ cd /c/pro
[Tab]
$ cd /c/project
[Tab]
$ cd /c/project
projectapp projectsys
$ cd /c/project
[a]
$ cd /c/projecta
[Tab]
$ cd /c/projectapp
- File and directory names are case sensitive under MinGW/MSYS.
- After starting an MSYS shell you will find yourself in your home directory
/home/[username], abbreviated with ~. It is not your Windows "my documents"
folder.
Important and useful commands
MSYS offers a set of feature rich command line tools. Except the shell internal commands, these tools can also be used in the cmd shell. To get information about the behaviour and valid command line parameters of a command, enter $ [command] --help
Common tools are:
- cd
- changes the current working directory; nearly the same as Windows' cd,
but does not allow the "shortcut" cd.. (without space between
cd and ..) and calling cd without parameters does not
show the current directory but changes to your home directory
- cp
- copies files and directories
- diff
- shows the differences between two (text) files or even whole directories
- exit
- closes the current shell ([Ctrl]+[d] does the same)
- find
- find a file
- grep
- searches a string or regex in a file, directory or stream
- make
- interprets Makefiles to build whole projects
- mv
- moves and renames files and directories (there is no dedicated rename command)
- less
- shows the content of a file or a stream page by page; better replacement for
Windows' more command (guess where the name comes from ...)
- ls
- lists the content of a directory and shows file attributes; powerful replacement
for Windows' dir
- mkdir
- creates a directory
- pwd
- shows the absolute path of the current working directory
- rm
- deletes files and directories
- sed
- stream editor, allows manipulation of files and streams
- tar
- packs or extracts files to/from archives
Links
- CCSC2SDCC Migration Guide -
This guide is more general; it can help to migrate awarecon related code but the
compatibility files mentioned in the guide are already contained in the libtools part of
the new Particle Base System.
- SDCC HomePage