Application Note

AN1405: Migrating from other Eclipse/GCC IDEs

to Atollic® TrueSTUDIO®

Copyright Notice

ii | P a g e

COPYRIGHT NOTICE

TRADEMARK

DISCLAIMER

The information in this document is subject to change without notice and does not represent a commitment of Atollic AB. The information contained in this document is assumed to be accurate, but Atollic assumes no responsibility for any errors or omissions. In no event shall Atollic AB, its employees, its contractors, or the authors of this document be liable for any type of damage, losses, costs, charges, claims, demands, claim for lost profits, fees, or expenses of any nature or kind.

DOCUMENT IDENTIFICATION

ASW-AN1405 December 2014

REVISION

Atollic AB Science Park Gjuterigatan 7 SE- 553 18 Jönköping Sweden

+46 (0) 36 19 60 50

E-mail: sales @atollic.com Web: www.atollic.com

Atollic Inc 241 Boston Post Road West (1st Floor), Marlborough, Massachusetts 01752 USA

E-mail: sales.usa@atollic.com Web: www.atollic.com

© Copyright 2014 - 2016 Atollic AB. All rights reserved. No part of this document may be reproduced or distributed without the prior written consent of Atollic AB.

Atollic, Atollic TrueSTUDIO, and Atollic TrueSTORE and the Atollic logotype are trademarks or registered trademarks owned by Atollic. ECLIPSE™ is a registered trademark of the Eclipse foundation. All other product names are trademarks or registered trademarks of their respective owners.

First version December 2014

Second version June 2016

+1 (617) 674-2655 (Voice) +1 (877) 218 9117 (Toll Free) +1 (978) 401 0680 (Fax)

List of Contents

iii | P a g e

Contents Introduction ...................................................................................................... 1

Intended Readers .............................................................................................. 2

Scope ................................................................................................................. 2

Requirements .................................................................................................... 3

Overview ........................................................................................................... 3

Import the project into Atollic TrueSTUDIO ...................................................... 4

Create an Atollic TrueSTUDIO project ............................................................... 5

Delete unnecessary resources from the new project ....................................... 8

Copy resources from the imported project to the new project ....................... 9

Build settings ................................................................................................... 10

Debug the application in Atollic TrueSTUDIO ................................................. 16

Common problems .......................................................................................... 20

List of Tables

v | P a g e

Table of figures Figure 1 - Import wizard ................................................................................ 4

Figure 2 - Archive file or root directory? ....................................................... 4

Figure 3 - Choose project type ...................................................................... 5

Figure 4 - Configure target settings, target-specific support and ARM generic

CPU core support ........................................................................................... 5

Figure 5 - Choosing a not supported board - means no SFR-register view! .. 6

Figure 6 - Configure runtime library options ................................................. 7

Figure 7 - Configure Debug probe (can be changed later) ............................ 7

Figure 8 - Delete all resources ........................................................................ 8

Figure 9 - Empty project “NewTSProject” as template ................................. 8

Figure 10 - Copy resources from the imported project to the new Atollic

TrueSTUDIO project ....................................................................................... 9

Figure 11 - All resources copied to Atollic TrueSTUDIO project .................... 9

Figure 12 - Tool settings tab ........................................................................ 10

Figure 13 - FPU settings ................................................................................ 11

Figure 14 - C-standard .................................................................................. 11

Figure 15 - Setup project global build symbols ............................................ 11

Figure 16 - Paths and Symbols ..................................................................... 12

Figure 17 - Include header-files.................................................................... 12

Figure 18 - Source Location .......................................................................... 13

Figure 19 - All source folders added and project root directory removed .. 13

Figure 20 - Linker script and Runtime library options. ................................. 14

Figure 21 - Example with multiple linker scripts .......................................... 14

Figure 22 - Include your static libraries ........................................................ 15

Figure 23 - Build toolbar .............................................................................. 15

Figure 24 - Startup script, enables GDB scripting pre and post breakpoint

insertion ....................................................................................................... 18

Figure 25 - The Debug perspective of Atollic TrueSTUDIO .......................... 19

Application Note

1 | P a g e

INTRODUCTION The intention of this application note is to provide guidance on how to migrate your development project into Atollic TrueSTUDIO from another Eclipse/GCC environment so that you can have the benefit of working with a professional, supported IDE, which includes a number of advanced tools to increase development efficiency and software quality.

The document will work as a tutorial on moving a development project created with an Eclipse/GCC environment into Atollic TrueSTUDIO.

Atollic TrueSTUDIO offers an ideal upgrade path from basic Eclipse/GCC IDEs because migration effort is minimal.

An Eclipse-to-Eclipse IDE migration requires minimum of GUI re-training

GNU-to-GNU command line tool migration removes need to rewrite the source code files

No change to the assembler file syntax

No change to the linker file syntax

No change to the makefile syntax

No change to the compiler #pragmas

No change to the inline assembly syntax

No change to the command line options (for script builds, etc.)

No change to compiler specific behavior (such as structure packing, bitfields, etc.)

No change to the compiler warnings

The main tasks during a migration from another Eclipse/GCC IDE is to get the build and debug configurations to work.

Application Note

2 | P a g e

INTENDED READERS The intended reader is any developer who is considering moving a project from another

Eclipse/GCC environment into Atollic TrueSTUDIO. Atollic has also written similar

application note documents covering migration from specific tools such as Freescale®

CodeWarrior or NXP™ LPCXpresso. If you are migrating from one of those tools, then

please read the related specific document, please visit this webpage for similar application

notes:

http://www.atollic.com/index.php/how-to-documents

The reader of this document do not need any prior knowledge of Atollic TrueSTUDIO in

order to be able to follow this tutorial. It is however advised that the Atollic TrueSTUDIO

User Guide is consulted in parallel to this document whenever questions arise. The User

Guide can be found in Atollic TrueSTUDIO Information Center.

SCOPE The scope of this document stretches from importing a project into Atollic TrueSTUDIO all the way to performing a successful build and being able to download and debug the application in the embedded target. For specific instructions on how to solve problems outside the scope of this tutorial there may be links to external resources.

In this tutorial we assume that you are intending to use the CDT Internal builder with Atollic TrueSTUDIO. This differs slightly from the default approach of some other Eclipse/GCC environments where the default setting is to let CDT auto-generate makefiles and use the external builder (make) to perform the build. This approach is also possible in Atollic TrueSTUDIO, but will not be described in this tutorial.

The reader is assumed to have exported his or her project from his/her Eclipse environment. Importing the project into Atollic TrueSTUDIO will be the starting point of this tutorial. Even though we will import an Eclipse exported project into Atollic TrueSTUDIO we will actually create a new project in Atollic TrueSTUDIO so that the Atollic TrueSTUDIO project is not cluttered with old and invalid project metadata. The imported project is only imported as a convenience so that we may copy resources from the imported project into the new Atollic TrueSTUDIO project.

You are assumed to be aware of how a project typically is imported and exported in Eclipse. Atollic TrueSTUDIO uses the same mechanism.

Application Note

3 | P a g e

REQUIREMENTS Atollic TrueSTUDIO v.5.x or higher. An evaluation license can be requested from

your distributor via www.atollic.com.

~1-2 hours of time

OVERVIEW The following steps are needed to migrate your Eclipse/GCC project into Atollic TrueSTUDIO

1. Import the exported Eclipse/GCC project into Atollic TrueSTUDIO

2. Create a new Atollic TrueSTUDIO wizard C Project selecting the right target MCU.

3. Delete unnecessary resources (files) in the new Atollic TrueSTUDIO project

4. Copy resources across from the imported project to the new project

5. Modify build settings

i. Verify FPU settings

ii. Choose C language standard

iii. Define symbols

iv. Setup include paths and source locations

v. Point out linker-script(s)

vi. Runtime library settings: Newlib or newlib-nano?

vii. Add libraries as necessary

6. Build the project

7. Setup a debug configuration

Application Note

4 | P a g e

IMPORT THE PROJECT INTO ATOLLIC TRUESTUDIO We are assuming that you have exported your Eclipse/GCC project as an archive file or file system (folder) containing the project(s) we need to import into Atollic TrueSTUDIO. Importing the project is done by starting Atollic TrueSTUDIO and start the import wizard.

File Import… General Existing Projects into Workspace

Figure 1 - Import wizard

Choose the option Existing Project into Workspace

Figure 2 - Archive file or root directory?

If you are importing a root directory (from a folder), then make sure that Copy projects into workspace is enabled! Click Browse and point out your exported Eclipse/GCC project.

Application Note

5 | P a g e

CREATE AN ATOLLIC TRUESTUDIO PROJECT The following section describe how you create a new application project in Atollic TrueSTUDIO. We will migrate the source code from the imported project into this Atollic TrueSTUDIO application project.

Figure 3 - Choose project type

Click in the toolbar File > New > C Project

o Give the project a Project name

o Select your desired project type Executable > Embedded C Project

o Click Next

Figure 4 - Configure target settings, target-specific support and ARM generic CPU core support

Application Note

6 | P a g e

Atollic TrueSTUDIO Hardware configuration is where you select which specific device or generic ARM CPU core you want to target with your project.

o Configure the target board/device correctly (try to use target-specific settings and configuring build/debug will become easier/better).

o Setup FPU settings by selecting floating point and floating point unit.

o Code location does not matter since we will use imported linker scripts instead.

Figure 5 - Choosing a not supported board - means no SFR-register view!

o Choosing a generic CPU core also means no SFR-view unless you supply the CMSIS-SVD XML-file yourself. It can be imported by SFR-view. Click Next!

If the Atollic TrueSTUDIO project wizard has specific support for your microcontroller or evaluation board, then make sure to use this selection! If your MCU/EVB is not listed in the wizard, you can instead choose Vendor > ARM, Microcontroller > your CPU core. To cover all cases the example below shows the more complicated case on how to deal with a not-supported MCU.

Application Note

7 | P a g e

Figure 6 - Configure runtime library options

TrueSTUDIO Software configuration defines the initial run-time library configuration for the project

o Choose the library Newlib or Newlib-nano. This can be changed at a later stage. Use the library that you were using in your old environment.

o Deselect tiny printf, selecting tiny printf will generate a source file implementing small memory footprint implementations on some printf-related functions. This can be imported at a later stage if necessary.

o Click Next

Figure 7 - Configure Debug probe (can be changed later)

TrueSTUDIO Debugger configuration gives the user a possibility to pre-select which debug probe that will be used to connect to the target.

o Choose your Debug Probe

Click Finish to end the project wizard and generate the new project

Application Note

8 | P a g e

DELETE UNNECESSARY RESOURCES FROM THE NEW

PROJECT Before we can import your project resources (files and folders) into the new project we need to remove the automatically generated resources. Delete all resources (files and folders) in the new project by selecting all folders (not Includes), press the delete button and click Yes to confirm.

Figure 8 - Delete all resources

Your new Atollic TrueSTUDIO project should now only contain Includes which are depending on the MCU chosen for the project. No other files should be stored in the project.

Figure 9 - Empty project “NewTSProject” as template

The Atollic TrueSTUDIO project called NewTSProject will be your new project where all project resources must be copied across to. So why did we bother importing the Eclipse/GCC project? It is easier to move/copy resources across the projects and try to see what builds and what does not build properly inside of Atollic TrueSTUDIO compare to using Microsoft windows File Explorer for this.

Application Note

9 | P a g e

COPY RESOURCES FROM THE IMPORTED PROJECT TO

THE NEW PROJECT

Figure 10 - Copy resources from the imported project to the new Atollic TrueSTUDIO project

Copy all folders from the old imported project, except the build output folder (typically Debug or Release) if such exists. Select and right-click to copy or just select all folders and drag & drop them into the new Atollic TrueSTUDIO project while holding down CTRL-key to make sure to copy rather than moving the files.

Figure 11 - All resources copied to Atollic TrueSTUDIO project

The result should look something like the above depending on how complex your project structure is!

If you have various project external dependencies and if you are using several libraries and software stacks the best approach is to try to keep them modularized as static libraries. Read more about how to setup a static library project in the Atollic TrueSTUDIO User Guide.

Application Note

10 | P a g e

BUILD SETTINGS The next step is to set up the build settings for the new project. Build settings are accessed by selecting the project (in this case NewTSProject), then clicking on the toolbar button on Project Build Settings…

This should automatically open up the Project Properties and more specifically the tab C/C++ Build Settings Tool Settings

Figure 12 - Tool settings tab

Some of the feature settings in the dialog boxes are available in standard Eclipse/CDT installations, and we will go through the most important ones and show some of the options that are unique to Atollic TrueSTUDIO.

Please note that all settings done are only applied to the Configuration currently being selected. See Figure 12. In order to apply settings to all configurations (Debug / Release) make sure to select Configuration == [All configurations]. This will reduce the amount of work needed when using multiple configurations.

Application Note

11 | P a g e

Figure 13 - FPU settings

FPU Settings. Unless you are certain that you made the right choice when creating the project, it is a good idea to double-check the FPU settings. This is done under the Target pane of each binary utility (Assembler, C Compiler, C Linker).

Figure 14 - C-standard

C language standard. Move to the C Compiler General. Double-check which C standard that the C Compiler compile accept.

Figure 15 - Setup project global build symbols

Symbols. If any symbol definitions are needed for conditional building these may be

defined in C Compiler Symbols (or Assembler Symbols for assembler)

The user must also configure which directories that are to be treated as source locations by

the build system and which directories that should be added as include paths. This can be

Application Note

12 | P a g e

set up in many different ways. The recommended way would be by using another set of

menu tabs found in Project properties C/C++ General Paths and Symbols.

Figure 16 - Paths and Symbols

Includes. In the Includes tab, you can specify which include directories the compiler

shall scan for header-files. Click Add… Workspace browse to your directory

containing header-files. The result could look like this.

Figure 17 - Include header-files

When Include paths to header-files have been added we must also tell the build system

which folders contain source code. This is done in the Source Location tab

Application Note

13 | P a g e

Figure 18 - Source Location

Source locations. Add all folders containing source code by clicking Add Folder… By enabling Add to all configurations, you will save yourself some unnecessary, redundant work. You only need to add the “parent-folders” as this property is inherited. It is never recommended to set the whole project root-directory to be a source location. Instead add all folders containing source code immediately below the project root folder as source locations.

Figure 19 - All source folders added and project root directory removed

When all source code locations have been added, this may trigger a re-build of the index in the project. If it is not triggered automatically, it is recommended to re-build the

Application Note

14 | P a g e

index manually for better source code navigation in the editor and other views. But first lets also look at some linker options that are necessary to setup

Linker options can be found under the Tool Settings C Linker

Figure 20 - Linker script and Runtime library options.

Runtime library. You can change whether you want to be using the Newlib-standard

implementation or the smaller Newlib-nano.

Linker script. If the project only uses one linker script then point to it in the Linker

script field. A recommendation is to use project relative paths where the current

folder is the build output folder (Debug or Release), therefore

“..\PATH\SCRIPT.ld” should do the trick.

Figure 21 - Example with multiple linker scripts

o If your project uses multiple Linker scripts than instead specify all scripts in

the C Linker Miscellaneous Other Options field. In the example used

here, there are three linker scripts used which are located in the folder

ldscripts in the project root-folder. These can be pointed out by adding:

-Wl,-cref,-u,Reset_Handler,-T,..\ldscripts\mem.ld,-

T,..\ldscripts\libs.ld,-T,..\ldscripts\sections.ld

Application Note

15 | P a g e

Figure 22 - Include your static libraries

Libraries. If you have dependencies on static libraries, you can add them in C Linker Libraries. Remember that the Library search path should be relative and should be pointing towards build output folder where the archive (.a) file is located.

When all these settings are copied across we have hopefully managed to migrate your

development project into Atollic TrueSTUDIO. Let us try to build the project!

Figure 23 - Build toolbar

Select the project and click Project Build or use the toolbar.

If you run into problem you may want to re-build the index so that it is easier to navigate

code.

Right-click on the project in the project explorer. In the context menu choose

Index Re-build. The IDE now is capable of navigating the new resources. For

instance, hyper-linking to header-files should now work!

Application Note

16 | P a g e

DEBUG THE APPLICATION IN ATOLLIC TRUESTUDIO When the project has been built properly you are ready to start a debug session.

Select the project root-node in the project explorer view

Toolbar: Run Debug (or simply hit F11)

If you have built more than one binary file in your project you will be prompted to select which binary you wish to debug as seen below. Please select your binary.

Figure 1 - Choose which binary to debug

Click OK

The next step gives you the possibility to change the Name of the debug configuration or

change which binary to debug. No action should be needed.

Figure 2 - A confirmation of your previous selection

Application Note

17 | P a g e

The second tab called Debugger, is however important. On the Debugger tab you will need to select the Debug probe that is used to interface with target, this was already setup in the project wizard when creating the project, but you can make changes here.

Figure 3 - Choose your debug probe

Setting up the debug configuration will be a little bit different depending on your choice of Debug probe and whether, from the beginning, you created the project for a specifically supported microcontroller or a generic ARM Cortex-M.

o If the project from beginning was created with target-specific support the startup script will be automatically generated for the chosen debug probe.

o If the project from beginning was created as a generic ARM Cortex-M core project you will need to write the startup script yourself. An advice would be to consult SEGGER manuals for the GDB-server and to generate a new Atollic TrueSTUDIO project for a similar microcontroller and generate a debug configuration for this device to enable copy-pasting most of the settings.

Select your debug probe

SEGGER J-Link/J-Trace? Requires almost no further configurations to get a simple debug session running. SEGGER also provide tracing using SWV and ETM with Cortex-M targets implementing these tracing mechanisms. Which be optionally enabled, selecting SWV or ETM as Trace system.

If the project was initially created as a generic ARM Cortex-M project, see Figure 4, then we must also tell the SEGGER J-Link GDB-server which microcontroller we are trying to debug, so that the debug connection is initialized properly and that flash writing becomes possible. This is not necessary if you instead created a target specific project when you generated your project. What if you don’t

Application Note

18 | P a g e

remember? This is easy to check. Move to the tab called Startup script which is the GDB-script that enables configuration with the microcontroller.

Figure 24 - Startup script, enables GDB scripting pre and post breakpoint insertion

It is important that the parameter monitor flash device is set up correctly so that the SEGGER GDB-server is able to set up a connection with target correctly. So how do I found my device name as it is recognized by SEGGER? Go here: C:\Program Files (x86)\Atollic\TrueSTUDIO for ARM Pro

5.2.0\Servers\J-Link_gdbserver\ETC\JFlash\MCU.csv. The MCU.csv file contains a list of supported MCUs as they are named and recognized by SEGGER GDB-server. Locate your MCU and insert it into the Startup script, i.e. monitor flash device = STM32F107VC

ST-Link JTAG probe? Provided that you created a target-specific project from the start the ST-Link will have its startup script generated properly automatically. If you instead chose a Generic ARM CPU core (see Figure 4) then you will need to write the script yourself. Please consult the ST-Link GDB-server manual, also generate a new project for another similar microcontroller and look at how the ST-Link GDB-script would look for this microcontroller this will probably give you the information you need.

If you are using the P&E micro debug probe, then please read this document: http://atollic.com/download/applicationnotes/AN1205_Using_PEM

icro_gdbserver_Guide_Draft.pdf

When you have confirmed that the Startup script is correct, then please click the Debug button

You will be automatically switched to the Debug perspective where you can control the debug session.

Application Note

19 | P a g e

Figure 25 - The Debug perspective of Atollic TrueSTUDIO

When you have come this far you are ready to start explore all the feature of Atollic TrueSTUDIO. In order to learn more on how to use Atollic TrueSTUDIO we recommend looking at our video tutorials on Youtube, and reading our User Guide. Links are available via the Information Center.

Help Information Center

Application Note

20 | P a g e

COMMON PROBLEMS

Please send feedback, questions and bug reports to support@atollic.com using the topics:

“AN1405 BUG: …”

“AN1405 FEEDBACK: …”

“AN1405 QUESTION: …”