Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.

Projects and Build Handbook for CCS

From Texas Instruments Wiki
Jump to: navigation, search

This page is no longer maintained and is kept here for reference only! Please go to this link for the most current version.

Introduction

This document is intended to serve as a "handbook" for all things related to Code Composer Studio Projects and its build environment. The document was originally written for CCSv5 but most of the content is applicable to CCSv6 and CCSv7 as well. Any areas where there are major differences will be noted. The document provides an overview of the CCS project and build system and the build flow of a typical embedded software program. It describes the different settings and properties that can be customized for a project. It also covers advanced topics such as portable projects, importing and building projects from command line and working with source control.




Projects Overview

This section provides an overview of workspaces and projects, types of projects and working with projects.

Workspaces and Projects

Workspaces

When CCS is started up, you will be prompted to choose a workspace. A workspace:

  • is the main working folder for CCS
  • contains information to manage all the projects defined to it
  • is the default location of any new projects created
  • stores user preferences, custom perspectives, cached data for plug-ins, etc

Multiple workspaces can be created and maintained

  • Only one can be active within each CCS instance
  • The same workspace cannot be shared by multiple running instances of CCS

For more information on workspaces refer to this page: Workspaces

Tip: It is advisable to periodically clean your workspace as they could get corrupted over time. Before cleaning, if there are workspace settings you'd like to preserve, you can save the current workspace settings so they can be imported into the new workspace.

  • To save settings: File->Export...->General->Preferences->To preference file
  • To import Settings: File->Import...->General->Preferences->From preference file

Short video clip on how to save/import workspace settings:



Note: Although it is the recommended method, not all settings are preserved using the above method.
Another way of saving all preferences is to copy over the '\.metadata\.plugins\org.eclipse.core.runtime\.settings' folder. This is only recommended if you are using the same version of CCS as the older workspace.

Workbench

Workbench refers to the main CCS GUI window that contains all the various views and resources used for development and debug.

  • One Workbench window can have visibility to all debuggable CPUs
  • Multiple Workbench windows can be opened ('Window->New Window')
  • Each Workbench window can differ visually (arrangement of views, toolbars and such), but refer to the same workspace and the same running instance of CCS. A project opened from one Workbench will appear to be open in all the Workbench windows

Projects

All work in CCS is based on projects, which are typically a collection of files and folders. Similar to the workspace, projects map to directories in the file system, so after a project is created, by default, it will be in a subfolder (of the project name) within the workspace folder. Projects can also be created in a directory outside the workspace, and this can be specified when creating a new CCS project. Once the project is created, a reference to it will be made in the workspace and the project is now visible and available for use from the Project Explorer view.

Project Explorer view

The Project Explorer view displays all projects defined in the active workspace. The view is mostly a representation of the file system of the project folder. Hence when creating a subfolder and moving files to that subfolder from within the Project Explorer view, the actual filesystem is being altered and vice versa (changes made to the filesystem will be reflected in the Project Explorer view). Note that not all files that appear in the view will exist in the filesystem and vice versa. Linked files will appear in the view but because they are references and not actual copies, they will not appear in the actual filesystem. The 'Binaries' and 'Includes' folders that appear in the Project Explorer view also are just references. The 'Binaries' folder points to the executable file in your active build configuration sub-folder (ex, 'Debug').

The screenshot below shows the contents of the 'c6748_sinewave' project in the Project Explorer view and how it maps to the physical project folder in the workspace in Windows Explorer. Note how the CCS generated project files(.ccsproject, .cproject, .project) and .settings folder shown in Windows Explorer are hidden in the Project Explorer view and how the 'Binaries' and 'Includes' folders in the Project Explorer view do not exist in Windows Explorer. Otherwise the rest of the folders and files are structured the same in the Project Explorer view and Windows explorer.

caption

Project Explorer View (left) and Windows Explorer (right)

In the Project Explorer view you can use filters to show/hide various file types to reduce clutter in the view.

Proj explorer filter.png



Types of Projects

Code Composer Studio supports a few different types of projects. When you create a new project, you can specify the project type. This project type will determine the toolchain, data and tabs that the build interface uses and displays.

  • CCS Project - type of project most commonly used when working with the TI toolchain.
    In this type of project, the make file is generated automatically.
    If you are working with TI processors and want to create a project to load and debug on a TI device/kit using JTAG this is the type of project you want.
  • C or C++ Project – standard Eclipse C or C++ project which requires an external toolchain such as GCC .
    The project wizard allows you to select a project type that can either generate makefile automatically or not. For eg, if you select the Project type to be “Executable, Shared Library or Static Library” , by default it will create the makefile automatically. If you select the Project type to be “Makefile project” it will not create makefile automatically. It is also possible to first create a “Executable” project, and then modify the project property to not generate makefile automatically.
    If you want to create a standard C/C++ project and have it use a toolchain such as GCC, this is the type of project you want.
  • Makefile Project with Existing Code – empty project that does not create makefile automatically.
    This is used for importing, modifying and building existing makefile based code.
    If you have a code base that has its own makefile but want to build the project through a GUI interface, this is the type of project you want. When creating the project you specify the location where the code and makefile reside, as well as the toolchain used for the build.

For more information on the different project types, as well as up-to-date documentation on CCS projects, refer to the CCS Online Help (menu Help->Help Contents).
For more information on standard Eclipse C/C++ Projects and Makefile projects, refer to the Eclipse online documentation

Creating New Projects

Projects map to directories in the file system, so after a project is created, by default, it will be in a subfolder (of the project name) within the workspace folder. Projects can also be created in a directory outside the workspace - this can be specified when creating a new project.

Creating New CCS Project

The steps for creating a new CCS project are described in the CCS Online Help topic under
Code Composer Studio Help->Tasks->Working with CCS Projects->Creating a new CCS Project

The steps for creating a new SYS/BIOS CCS project are described in the CCS Online Help topic under
SYS/BIOS->Getting Started Guide

Another online resource that walks through the steps of creating a new CCS project is
GSG:Creating projects v5

As part of the New Project wizard CCS provides several example templates to ease the process of getting started. You can select from templates such as “Hello world”, “Blink LED”, “Empty Project” and so on. These templates will add all the source files required to build that program and load and run it on the device.

NEW IN CCSv6: The New Project wizard in CCSv6 looks slightly different than the one in CCSv5 in terms of the layout of the fields. Multi-core devices now show each core as a tab (as shown in the screenshot below) so you can easily switch between the tabs to create projects for the desired core.

New project wizard1.png

NEW IN CCSv6: Also new in CCSv6 is support for creating and building CCS projects with GNU compilers - Red Hat GCC for MSP430 and Linaro GCC for ARM Cortex. The compiler selection can be made from the Compiler version field's drop-down menu.

Msp compiler selection.png

More information on using MSP430-GCC with CCSv6 is in this page:
Using MSP430-GCC with CCSv6

Creating New C/C++ Project

The general steps for creating a new managed make or standard make C/C++ project are described in the Eclipse online documentation:
http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.cdt.doc.user%2Ftasks%2Fcdt_t_proj_new.htm

This page walks through the steps of creating a GCC project in CCSv5:
How to create GCC projects in CCSv5

Creating New Makefile project

The general steps for creating a makefile project are described in the Eclipse online documentation:
http://help.eclipse.org/luna/topic/org.eclipse.cdt.doc.user/getting_started/cdt_w_newproj.htm?cp=10_1_2



Adding or linking source files and folders to project

Files and/or folders can either be added or linked to a CCS project before it can be built as part of the project.

When a file/folder is added to a project, it is physically copied to the root location of the project directory.
There is also the option to link a file/folder to a project. This will simply have the project create a reference to the file/folder instead of copying it into the project directory. 'Linked' files appear in the CCS project explorer view with a special icon as shown below.

Linked file icon.png

To copy or link files to a project, you can either:

  • go to CCS menu Project->Add Files, and select the file(s) you wish to add, or
  • select the file(s) in Windows Explorer and drag and drop them into the project in the Project Explorer view

You will then be prompted as to whether you want to “Copy files” or “Link to files”, so you can choose the option you desire. You can also choose if you want to link files relative to a path variable as described in the Portable Projects page. This is desirable for projects that will be shared among multiple users. Files that are "linked" to a project will be listed in the .project file under <linkedResources> tag.

Video walk-through of adding files to a project:



To copy or link folders to a project, you can either:

  • select the folder(s) in Windows Explorer and drag and drop them into the project in the Project Explorer view (for copying or linking), or
  • follow the procedure in this page (for linking)


If you find that the "Link to files" is not working as expected, for example, the file does not appear in the Project Explorer view after the selection, please check that your Drag and Drop Settings has "Enable linked resources" enabled.

Linkfile1.png

Linkfile2.png

Note: Since linked files actually reside in a location outside the project folder, be aware that editing these files will modify the file not only for the current project but also for any other project that links to the same file.


All files that are physically in the project folder will be included in the project build unless specifically excluded. To exclude a file from build, refer to Exclude files from build.


Export resources to Archive File

If there is a need to identify/get a copy of all source files that are part a project (whether copied or linked) so they can be saved to a code repository, the resources can be exported to an Archive file. To do this, right-click on the project in the Project Explorer view, select Export, expand General and choose Archive File. Click on Next. Specify the name and location of archive file and click Finish. The resulting archive file will contain a copy of all the resources in the project, whether they were copied or linked.

NEW IN CCSv7: In CCSv7, there is a checkbox that should be explicitly selected if you wish to export linked resources. Be sure to enable that checkbox and select all the desired linked resources.

Export archive.png




Virtual folders

Virtual folders are folders that exist only in the Eclipse workspace tree, and have no file system location. By using virtual folders, file and folders can be organized in a project hierarchy independently of the file system location of those resources.

Regular file and folder resources can not be created under a virtual folder. Only other virtual folders or linked resources can be created directly under a virtual folder.

Please see this quick tip video for more information on using virtual folders for organizing your projects.




Importing projects

Any project that you want to work on must be imported into CCS. This is equivalent to what one might think of as "opening" a project. CCS can import projects that were created with the same version or older versions of CCS, including legacy CCSv3 projects.

To import a project (other than CCSv3 project), go to menu Project->Import Existing CCS Eclipse Project and browse to the location of the project. If the project is located outside of the workspace, you have the option to either copy the project into the workspace or not. If you check the box to "Copy project into workspace" the project will be physically copied into the workspace folder. If the box is not checked, the project will still reside in its original location and all modifications/actions taken on the project will modify it in its original location.

Note that the "copy to workspace" checkbox means that everything in the project folder will be copied to the workspace, that means the project files and any source files that are present within the project folder. If the original project has linked resources those will not be copied to the workspace. Hence, make sure to check if the project references other linked files and resources from another location before directly editing such files. Refer to this section on linked files if needed.

There is another way to import a project, using the menu File->Import->General->Existing Projects into Workspace. This is ok to use if the project is a standard Eclipse C/C++ project. However, for a CCS project you should use the menu Project->Import Existing CCS Eclipse Project.

To import a legacy CCSv3 project, use the menu Project->Import Legacy CCSv3.3 Project and browse to the location of the CCSv3.3 project.

Note:

  • Depending on how the original project was created (whether it was made portable or not) it may not be advisable to check the box to copy project into workspace as it could break paths to some of the resources.
  • The latest release of several TI example projects (such as those in Stellarisware, Tivaware, ControlSuite) are designed such that they can be safely copied to workspace.

Resource Explorer

Starting with CCS 5.2, another way to quickly import a TI provided example project from common software packages (like SYS/BIOS, ControlSuite etc) into CCS is through the Resource Explorer. The Resource Explorer can be opened from CCS menu Help->Welcome to CCS or from View->Resource Explorer. From there you can browse the software packages and example projects that are available for import. Projects imported using Resource Explorer will be inherently copied to workspace.

Resource explorer import.png

Starting with CCSv7, the Resource Explorer is operating online and the interface is different. The new Resource Explorer helps you browse examples for your chosen platform, download software packages and import projects all from within that interface. More information on the new Resource Explorer is available here.

The older Resource Explorer interface is still included in CCSv7 and can be opened from menu View->Resource Explorer Classic.


Project Import Fails

If a project import fails with the error:
“Error: Import failed for project 'abc' because its compiler definition is not available”. Please install the X.Y.Z compiler before importing this project…”
please see the following article for details on why this error appears, and how it can be fixed: Importing CCS Projects

Variables in imported projects

The variable PROJECT_ROOT is set by CCS, by default, to the project's root folder (the folder that contains the .*project files). When a project is imported (with the "Copy project into workspace" checkbox enabled), CCS will create a new variable/macro named ORIGINAL_PROJECT_ROOT whose value is set to the original project's root directory. If the original project used the macro ${PROJECT_ROOT} in any paths such as compiler include paths, it will be replaced by ${ORIGINAL_PROJECT_ROOT} in the imported project. This is done because the project may still need to reference resources whose paths are set up relative to the original project location, and hence will need to be preserved.

Many projects are structured such that the include files reside in a common folder and several projects can use/reference the same set of common include files. Several TI software packages such as TivaWare, ControlSuite are set up this way. When projects from these packages are imported and copied to workspace, the include folders are not necessarily copied over. So, if the original project has compiler include paths set up relative to the variable PROJECT_ROOT, those paths will be converted to use ORIGINAL_PROJECT_ROOT after project import, so the include files are still correctly referenced relative to the original project.

If you wish to specify include paths to always be relative to the current project directory, the variable ProjDirPath should be used instead.

Other resources:
Importing Projects into CCS
Importing Projects
Importing CCSv3 Projects into CCSv4




Open/Closed projects

Projects in CCS can be either open or closed. When a project is imported into the workspace it is automatically open. When a project is closed, it is still defined to the workspace, but it cannot be modified by the Workbench. The resources of a closed project will not appear in the Workbench, but the resources still reside on the local file system. Closed projects require less memory and are not scanned during routine activity. Hence closing unnecessary projects can improve performance of CCS. Note that closed projects will still be visible in the Project Explorer view, but with a 'closed' folder icon.

Open closed project1.png

Projects can be opened or closed by right-clicking on the project name in the Project Explorer view and selecting Open Project or Close Project respectively.

Renaming projects

To rename a project that is open in the Project Explorer view:

  • Right click on the Project and select Rename
  • Give it a new name and click OK

Copying Projects

In some cases, it may be necessary to make a copy of a project so you can make changes to the copied version rather than the original. To make a copy of a project that is open in the Project Explorer view:

  • Right click on the Project and select Copy
  • Right click in the Project Explorer view and select Paste
  • In the Copy Project dialog
    • give the new project a different name, and
    • use the default location or specify a different location

Note that copying a project using this menu will copy over the files/resources from the original project folder into the copied project folder. However, if the project contains any linked resources they will still point to their original location. Hence, make sure to check if the project references other linked files and resources from another location before directly editing such files. Refer to this section on linked files if needed.


When a project is copied to another project, the new project "name" is saved in the .project file. This is the name by which the new project is identified and what you would use if you wish to import the new project via command line. However, many other settings (like name of output file, map file) and build definitions are kept the same as the original project until user goes in and changes those as well. For this reason the .cproject file of the copied project may still contain references to the original project name.

In the copied project, if you go into the Properties->Variables tab, and enable Show System Variables, you will see that all build paths have been adjusted to the location of the copied project, however, things like BuildArtifactFileBaseName and BuildArtifactFileName are still kept as the old names. If these variables are used in specifying the output file name, map file name etc, then they will still have the old name. It is left to the user to make further customizations to these properties, and if they are done, they will reflect in the .cproject file.

Creating copy of example projects

TI provides many example CCS projects as part of their software offering. For example, the ControlSUITE software infrastructure for C2000 devices, TivaWare for Tiva devices, BLE-Stack for SimpleLink devices etc. include several example projects to jump-start the development process. If you want to make a copy of an example project provided by TI into a separate directory so you can make changes to any of the source files in it without fear of corrupting the original example, then check the guidelines in this article: Creating copy of example project



Project Files and Build System Overview

Create Project

When a new CCS project is created in CCSv5/CCSv6/CCSv7, the following project metadata files and folders are created in the project folder:

  • .ccsproject: Stores project settings contributed by TI
    • Ex: Stores initial device/toolchain settings entered by user at project creation
  • .cproject: Stores project settings contributed by CDT (C/C++ Development Tooling)
    • Ex: Stores most of the build properties under the ‘Build’ section (most of the compiler/linker options)
  • .project: Stores project settings contributed by Eclipse
    • Ex: Stores information for linked resources, linked resource variables, resource filters
  • .settings (folder): Stores project specific settings that differ from the default CCS settings (workspace preferences)
  • makefile.defs (SYS/BIOS): Additional make rules included by the generated project makefile for SYS/BIOS projects

The .ccsproject file holds a snapshot of selections made at the time of project creation, and rarely changes after that. So if you change properties such as the device-variant or compiler tools version, the change is not stored in the .ccsproject file, but instead stored in the .cproject file.

The .ccsproject file is mainly a historical left-over from the days when some settings were stored on a project-level (as opposed to build-configuration-level). But the file is still currently used to:

  • Allow the user to roll back certain settings to their original values
  • Store some project-wide settings, such as the connection for debugging. (Maybe other settings in the future).

Although it seems like this file stores some unnecessary information, it could be helpful when trying to debug issues.


The .ccsproject, .cproject, .project files are XML files. It is generally NOT recommended to manually edit these files unless you are an expert user and have an understanding of what you are modifying.




Build/Rebuild project

When a CCS project is built for the first time or rebuilt, it goes through the following steps:

  1. Auto-generate makefiles:
    Generates main makefile and several *.mk include files in the active project configuration folder (such as \Debug folder, by default)
    • makefile: Main makefile that includes the generated *.mk files
    • All of the sources participating in the build are defined in the below *.mk files
      • objects.mk
      • sources.mk
      • subdir.mk
      • subdir_vars.mk
  2. Optionally clean using 'gmake' (when selecting Rebuild Project or Clean Project)
    Deletes .obj, .pp and .out files in the active configuration folder (such as \Debug folder, by default). It does not delete makefiles and .map files
  3. Build the main makefile using ‘gmake’
    The main make build in turn invokes the pre-build (if any), main-build and post-build (if any) steps.
    These steps are described in more detail below.

Makefiles

The makefile auto-generated by CCS includes a few other files, namely makefile.init, makefile.defs and makefile.targets. <p> makefile.defs is used for defining additional make rules for SYS/BIOS projects.
makefile.init and makefile.targets are not used by the TI build environment.
They are inserted into the makefile by one of the Eclipse components(CDT) and can be used to extend the behavior. For example, you can create these optional makefiles in the top-level folder of the project:

  • makefile.init -- included early in the build
  • makefile.targets -- for adding rules for additional make targets

Each file, if it exists, gets included at a specific point along the build. You can take a look at where they get included by taking a look at the makefile in the active project configuration folder.

For example, if you wish to add some additional clean commands (ie perform some clean actions in addition to what the default clean does) you could do the following:
1. create a makefile.targets that contains rules for the additional make targets and place the file in the top-level folder of the project. For example, a makefile.targets file to perform additional clean commands (in this case, delete the main.asm file) could look like this:

myclean:
-$(RM) "main.asm"
-@echo 'Finished my custom clean'

2. modify the Build->Behavior tab in CCS to add "myclean" in addition to the default clean.
Custom clean.png

Now when selecting Clean Project, it will perform the default clean as well as the custom myclean rule, as shown in the output below.

**** Clean-only build of configuration Debug for project test_f28377D ****

"C:\\CCStudio_v6.1.1.00022\\ccsv6\\utils\\bin\\gmake" -k clean myclean 
DEL /F "test_f28377D.out" "test_f28377D.hex" 
DEL /F "main.pp" 
DEL /F "main.obj" 
'Finished clean'
' '
DEL /F "main.asm"

'Finished my custom clean'


As additional reference, here are some external web posts that touch on the subject of these makefiles:
http://www.eclipse.org/forums/index.php?t=msg&goto=153134&
http://stackoverflow.com/questions/25575244/eclipse-cdt-generate-makefile-with-makefile-init-makefile-defs-makefile-target


To summarize, a typical project build looks like the following:

Project build flow.png

Pre-build

Pre-build steps are steps that you want to run before the main project build takes place.

For details on setting up and using the pre-build step in CCS, see the section Pre and Post Build Steps.

Main build

When a project is built in CCS, the main build is the step where the build commands and input files are passed to the RTSC and Compiler tools. RTSC tools are invoked only for projects that involve RTSC components (IPC, SYS/BIOS etc) and are called prior to the compiler tools. Each build tool takes in a set of input files and generates a set of output files.

The figure below shows a typical software development flow and gives an idea of the build tools and files involved when you build a CCS project. All of this is handled in the background by the makefile, however it is helpful to have an understanding of this build flow to be able to make better sense of the build output in the CCS build console.

The build tools components are highlighted in blue and the input/output files are highlighted in white . The RTSC Tools portion is dotted to show that it comes into play only when working with RTSC projects.

Main build flow.png

The most common path of software development flow is the straight path going from C/C++ Source Files down to the Executable file through the Compiler, Assembler and Linker. The Assembler step usually runs in the background and is hidden from the user. The Archiver and Library build utility are peripheral functions that enhance the process and may or may not be run depending on the requirements.

If the project is a RTSC project, the XDCtools run first and generate output files that are then passed to the compiler and linker.

For more information on each of the tools shown in figure, please see the references below:

  • Compiler: accepts C/C++ source files and produces assembly language source code.
    See the Compiler Users Guide for your specific processor family.
  • Assembler: translates assembly language source files into machine language relocatable object files.
    See the Assembly Language Tools Users Guide for your specific processor family.
  • Linker: combines relocatable object files into a single absolute executable object file. It accepts relocatable object files and object libraries as input.
    See the "Linker Description" chapter in the Assembly Language Tools Users Guide for your specific processor family.
  • Archiver: allows you to collect a group of files into a single archive file, called a library. It also allows you to modify a library by deleting, replacing, extracting, or adding members.
    See the "Archiver Description" chapter in the Assembly Language Tools Users Guide for your specific processor family.
  • Library build utility: allows you to build customized run-time-support libraries.
    See the mklib wiki page and Assembly Language Tools Users Guide for your specific processor family.
  • XDCtools: provides configuration tools used to create and build a static configuration as part of your application.
    See this wiki page and Using RTSC with CCStudio v4.


For more information on some of the input and output files in a typical CCS project build flow refer to the topic below

Files in CCS Projects

Post-build

The main build step discussed above results in a executable file (.out). This file can be directly loaded to a target device and debugged using Code Composer Studio, or can be converted to a hex format and programmed to a target device by a hex programmer. Other types of post processing can also be performed on the .out file using utilities included with the compiler tools.

The figure below shows some of the typical post build operations.

Post build.png

For more information on each of the tools shown in figure, please see the references below:

  • Hex conversion utility: converts an object file into other hex formats.
  • Absolute Lister: accepts linked object files as input and creates .abs files as output. You can assemble these .abs files to produce a listing that contains absolute, rather than relative, addresses.
  • Cross-reference Lister: uses object files to produce a cross-reference listing showing symbols, their definitions, and their references in the linked source files.
  • Object file utilities: comprises of utilities such as Object File Display utility, Disassembler, Name utility and Strip utility.

Details on all the above tools are in the Assembly Language Tools Users Guide.

For details on setting up and using the post-build step in CCS, see the section Pre and Post Build Steps.



Project Properties

There are many settings that define the properties of a project, such as the toolset used for the build, compiler and linker build options, project dependencies and environment variables, to name a few. These settings can be viewed and customized through the Project Properties. This section describes the more commonly used settings for a project.

General Properties

If you right-click on a project and go to Properties, then click on General in the left pane, the right pane will display a Main tab with general settings of the project such as:

General properties.png
  • Output Type
  • Device details
  • Compiler tools version
  • Output format
  • Linker command file
  • Runtime support library

For more information on Linker command files and Runtime support library, see Linker command files and Runtime support library.

The Output format field determines the format of the executable (.out).

In some cases, for imported projects, there may be Compiler version and Effective compiler version fields. The Effective compiler version field is the version of compiler tools being used for that build. If the project was originally created with a version of compiler tools different than what is installed in your machine or what CCS is set to use, then the Compiler version field will list that value. This is important to understand in order to know exactly which version of compiler is being used to build your project.

NEW IN CCSv6: In CCSv6, rather than the Effective compiler version field, the compiler version actually used for the build will be shown in the Compiler version field itself as shown below.
Effective compiler version.png

General properties rtsc.png

If the project is a SYS/BIOS project, in addtion to the Main tab there will also be a RTSC tab. The RTSC tab contains the following:

  • version of XDCtools used for build
  • RTSC Products and Repositories available and enabled (latest version is enabled by default)
  • Target
  • Platform
  • Build-Profile

The Target field is automatically populated based on the device variant selected in the Main tab.
The Platform field is selectable by the user based on the target board they are working with.
The Build-profile field shows which RTSC and SYS/BIOS libraries you want the configuration build to link with.

The Build-profile selection applies compile options to the C file generated when building the RTSC configuration (.cfg). Note that this is different from the compile options selected under Compiler Properties that apply to the user source code. If you choose the "release" RTSC profile, for example, a "-O2" option may be added to the build, while for the "debug" RTSC profile, there would not be a "-O2". Building with "release" is a good choice as the RTSC and SYS/BIOS runtime functions will be faster and will use less code memory. Building with "debug" makes the build faster, but the runtime application will be less efficient.

Build Properties

If you right-click on a project and go to Properties, then click on Build in the left pane, the right pane will display several tabs. The settings in each tab are described below. More details on these settings and their usage come in later sections.


Builder: Defines the build command and makefile generation
Advanced users may wish to customize the gmake command or even use a different make utility, but most users will not need to adjust the default settings.
See Changing the make utility if you wish to use a make utility other than the default gmake.

Behavior: Defines build settings and workbench build behavior
By default, the build setting "Stop on first build error" is unchecked. This passes the -k (--keep-going) option to gmake that tells it to "keep going" or continue with the build as much as possible after an error. If this box is checked, the -k option will go away and the build will stop at the first build error. Removing the -k option may be a desired setting if using a custom build step .

There is also an option here to Enable parallel build. This can be used to take advantage of PCs with multiple cores to run parallel builds and thereby speed up the build time.
See Parallel builds if you wish to enable parallel builds.

Steps: Pre-build and Post-build steps
Pre-build steps are steps that are to occur before the main project build takes place. Post-build steps are steps that are to occur after the main project build takes place.
See Pre and Post Build Steps.

Variables: Displays Build variables
Enabling Show system variables shows all system level and built-in variables, otherwise only project level variables are shown. Build variables can be used in compiler and linker build options, for example, to specify paths to include files or libraries relative to a build variable.
See Portable Projects for more information.

Environment: Defines environment variables and their use

Link Order: Defines the order in which files are passed to the linker
If you need strict control over the linking order you can add the required files here and control the order in which they get passed to the linker.

Dependencies: Defines dependencies between projects, allowing referenced projects to be built before dependent project.
See Project Dependencies for more information.


Under the Build category there are sub-categories called Compiler and Linker for setting options passed to the code generation tools. For a SYS/BIOS project, there is also a sub-category called XDCtools.

Compiler/Linker: Compiler and Linker options
There are several compiler and linker options available to control your build. The list of options is too vast to go into detail here. Refer to the Compiler and Assembly Language Tools Users Guides for options supported by the compiler and linker respectively. In the CCS Build Properties dialog, these options are categorized into groups for easy identification. You can drill down into the Compiler and Linker sections in the CCS GUI to access all of the available options.

Additional compiler and linker flags can also be set directly to the build command via the "Set Additional Flags" button. Note, however, that once set, the flags cannot be removed or edited using the same dialog box. They can be removed through the GUI options or edited by modifying the .cproject file in the project folder.

Set additional flags.png


XDCtools: XDCtools options
Refer to the SYS/BIOS Users Guide and RTSC-pedia web site for supported options.




Advanced Project Settings

If you right-click on a project and go to Properties, then click on Show advanced settings at the bottom of the left pane, a few additional entires will appear. The C/C++ General selection allows access to settings for Code Analysis, Indexer, Code Style and others.

Code Analysis

This is the built-in static code analyzer that comes with Eclipse that reports on programming errors, syntax and semantic errors, etc. The default settings are set at workspace level, but can be configured at either workspace level or project level.

Code analysis.png


By default, code analysis is disabled for CCS projects. This is because the rules defined in the Eclipse static analysis tool is somewhat different then what is defined by the TI tools, so the analysis tool could trigger errors where the TI tools do not. To confirm this, if you go into Project Properties for a CCS project, then to C/C++ General->Code Analysis->Launching, you will see that the "Run with build" and "Run as you type" boxes are unchecked. However, if you select Code Analysis in the left pane, and click OK, then it turns on the checks for that project, so you may start seeing errors in the CCS editor view.

If you would like to leave them on, you can also disable or customize individual settings (either at project or workspace level) by going into Project Properties->C/C++ General->Code Analysis. To customize specific items, select the item and click on Customize Selected.

Once the checks are turned on for a project, the following steps can turn it off again:
Clean out the Problems view and then Refresh the project. To clean out the Problems view, highlight and select all the messages in the Problems view and hit delete. Then close the source file from the editor view. Right-click on the project and click Refresh. Then open the source file again and the errors should be gone.



Indexer

This is the built-in Eclipse parser. It parses source and header files in the project to provide basis for C/C++ search, navigation features and content assist. The default settings are set at workspace level, but can be configured at either workspace level or project level or can be disabled completely.

Indexer.png

In some cases, there may be "Syntax" errors or "Symbol could not be resolved" errors reported by the indexer (they are usually highlighted in the editor margin) even when there is no issue with the build itself (ie, the compiler tools do not report any errors). The first thing to check, especially if you are the only one experiencing such errors on a known good project, is to open a new, clean workspace and re-import the project into it. If the errors persist or you experience these in your own custom project, you can look at adjusting the indexer settings or even disabling the indexer. This can be done from Project Properties->C/C++ General->Indexer. However, disabling the indexer completely means losing capabilities such as code completion and navigation to declaration/definition. A better option may be to disable the indexer markers without disabling the indexer itself. This can be done by going to Window->Preferences->General->Editors->Text Editors->Annotations and uncheck all three checkboxes for "C/C++ Indexer Markers".

Rebuild Index

If you find the advanced editor features such as Code completion, Open declaration etc. not working correctly, it could be due to a corrupted database/cache. In this case, rebuilding the Index could resolve the issue. To Rebuild the Indexed database for a project, right-click on the project in the Project Explorer view and select Index -> Rebuild.



Parallel builds

When working with large projects (with large number of source files) that take a long time to build, it can be beneficial to enable parallel builds that take advantage of the dual or quad core PCs that are very common these days. Enabling parallel builds, when following some general guidelines, can greatly speed up compilation time.

Parallel build.png

In CCS 5.3 and higher, to enable parallel builds, right-click on the project in Project Explorer view and go to Properties->Build->Behavior tab, and check the box to Enable parallel build.

You have the option to select the number of parallel jobs. Choosing the optimal number is usually a matter of trial and error. A good starting point is to configure the number of jobs to be equal to the number of processors in your computer, and then try increasing the value to see if further gains can be achieved. Note that setting the number of jobs to a value much higher than the number of processors in your computer or setting it to use unlimited jobs may result in the system using up more memory and becoming sluggish.

Note that when parallel builds are enabled, the messages/banners in the CCS build console will be interleaved due to the multiple jobs running at the same time.

Below is a short video demo:



NEW IN CCSv7: Parallel builds are enabled by default in CCSv7.




Pre and Post Build Steps

As part of the CCS build, you can define pre-build and post-build steps.
Pre-build steps are steps that you want to run before the main project build takes place. The pre-build step is always executed even if the state of the main build is up to date. An attempt to execute the main build will occur regardless of the success or failure of executing the pre-build step.
Post-build steps are steps that you want to run after the main project build takes place. The post-build step is not executed if the state of the main build is determined to be up to date. It will be executed only if the main-build has executed successfully.

One common use-case for post-build step is to convert the executable (.out) created by the project into a hex or binary format using the hex converter or other utilities such as tiobj2bin. The hex converter is part of the compiler toolset (can be found in \ccsv5\tools\compiler\<device>\bin within CCS installation) and tiobj2bin is included with CCSv5 ( can be found in \ccsv5\utils\tiobj2bin within CCS installation)

To set pre and post build steps in CCS, right-click on the project in the Project Explorer view, go to Properties->Build->Steps tab and enter the desired command in the Command fields.

Under Apply Predefined Step there are a couple of predefined post-build steps such as converting the executable to Intel-hex or TI-TXT format. If you select one of them the command will be automatically populated. It is still advisable to double-check that the options in the command are applicable and correct for the processor you are working with and your application requirements.

Post build step1.png

If you wish to convert the executable to binary format (.bin), the following command that utilizes the tiobj2bin utility can be used as post-build step:

"${CCS_INSTALL_ROOT}/utils/tiobj2bin/tiobj2bin" "${BuildArtifactFileName}" "${BuildArtifactFileBaseName}.bin" "${CG_TOOL_ROOT}/bin/ofd2000" "${CG_TOOL_ROOT}/bin/hex2000" "${CCS_INSTALL_ROOT}/utils/tiobj2bin/mkhex4bin"

Be sure to replace ofd2000 and hex2000 with the respective binaries for your device, for example, ofd6x and hex6x(for c6000) or armofd and armhex(for ARM).

Note: the examples in software packages like Stellarisware/TivaWare and AM335x Starterware already a similar post-build, which you can use as reference as well.

Running Multiple commands:
If you have more than one command to run, you can either put all of them in a batch file/shell script and call the batch file in the Command field, or you can use the applicable command processing symbol for running multiple commands on one line (cmd1 & cmd2 for DOS).
See FAQ: FAQ_-_CCSv4#Q:_How_do_I_specify_multiple_post_build_commands.3F_There_is_only_one_command_field.

When invoking batch files, a question that often comes up is whether the batch file can access CCS variables such as CG_TOOL_ROOT etc, so for example, variables within the batch file automatically change as the compiler version changes. You cannot directly access CCS variables from within the batch file, but you could pass it as an argument to the batch file.

So, for example, you could do something like this in the batch file:

@ECHO OFF 
set HexUtil=%1%
set CCSOutFile=Project.out
%HexUtil% -a %CCSOutFile%

and invoke the post build step as:
postbuildstep.bat "${CG_TOOL_ROOT}/bin/hex2000.exe"

NEW IN CCSv6: In CCSv6, the fields for pre and post build steps looks a bit different. The field now allows for multiple commands to be added, each on a new line.

Pre post build.png

The Apply Predefined Step has been removed since the hex utility integration is different in CCSv6. You can go into the Project Properties, enable the Hex Utility and then have access to all the options available for the utility.

Hex enable.png

TIP: If you wish to add some custom steps or call a batch file after the compile step but before the link step, you can add a pre-link step to the command field in the Linker options, as shown below. You basically prepend the custom step before the existing command and separate with an ampersand. The below example adds a pre-link step to call a batch file.

Pre-link-command.png



Changing the make utility

CCS uses gmake (GNU make) to build projects. If you have a need to use a different make utility or a custom build step, you can do so by right-clicking on the project in the Project Explorer view and going to Properties->Build->Builder tab and uncheck Use default build command. Then in the Build Command field type in the custom command to use for the build.

You can also use this if you want to simply modify the build command to pass additional options to gmake.

Note that when using a custom build step, you may want to enable the build setting "Stop on first build error" in the Behavior tab. If this is not enabled it will add a -k (--keep-going) option to the end of the command (for gmake, this option tells it to "keep going" or continue with the build as much as possible after an error), which may not be desired for certain custom build commands.

Note: This setting has to be changed at the project level. There is no global way to change the default builder or builder options.

Builder gmake1.png



Project Dependencies

Many times a main project may be dependent on other projects. A common use case is when a main project links in a library and the project for the library is set up as a referenced project. The idea here is that when you build the main project, the referenced project (in this case the library project) will be built first and then the main project.

Project dependencies can be set up when creating a new CCS project or from the Project Properties of an existing project. In order to create a dependency, all referenced projects must be in the same workspace as the main project.

To create a dependency, right-click on the project in the Project Explorer view and go to Properties->Build->Dependencies tab. Click on Add, choose the project to add to the list of references and click OK.

Dependency1.png

The Referenced Build-configuration column allows for choosing which build configuration to use when building the referenced project. Note that this setting will apply for the active build configuration of the main project. With these settings, you can control which build configuration of the referenced project will be built prior to building a specific build configuration of the main project.

Dependency2.png

Below is a short video that demonstrates Project Dependencies:

File specific options

It may be required that certain source files in a project be built with some specific compiler options different than the project level options. An example may be when specific files require a higher or lower level of optimization than other files. This can be done by setting those options at a file specific level. To set file-specific options, right-click on the file in the Project Explorer view, go to Properties, and set the desired options.

Files with file-specific options will have a special icon that looks like a push pin as shown here.

File specific option.png

To revert the file back to its default settings, right-click on the file, go to Resource Configurations->Reset to Default. Select the resource configuration to restore to default settings and click OK.

File specific restore.png

The push pin icon will disappear when the settings revert back to default.

The same procedure can be used to set custom options at a folder level. This video has a short demonstration:

When you add file specific options, what is actually happening is it will add a section in the project metadata files to indicate that there are file specific options for that file and what default options to override. When you use the Resource Configurations->Reset to Default option on the file, it will remove that whole section. Hence the project sees it as not having any file specific options in the project anymore and the special icon is removed for that file.

If you instead go to the file's properties, and click on Restore Defaults to restore the options back to default, it does not remove the icon because even though the override options are removed (hence no default options will be overridden), that special section for the file is still there. Basically it is using the default options, but because of the simple existence of the section, CCS keeps the special icon there.


If you wish to know which file specific options are set for a certain source file, there are a couple of ways to find this out:

  • Using the GUI: Right-click on the source file, go to Properties, and browse through the options. The file specific options will be highlighted in bold.

File specific option bold.png

  • Look at the .cproject file in the project folder: When file specific options are added, a section is added to this project file (look for it between <fileInfo> tags).


Exclude files from build

By default all files and folders within the CCS project folder are assumed to be part of the project build. To exclude file(s) or folders from the CCS project build, right-click on the file or folder in the Project Explorer view and go to Resource Configurations->Exclude from Build. In the pop-up dialog select the build configurations for which you want to exclude that file.

Note: With the default settings, files (or folders) excluded from build will appear grayed out in Project Explorer view as shown below.

Exclude from build.png

If you find that the file(s) excluded from build are not visible in the Project Explorer view at all, check if the below option is enabled in the view filter for the Project Explorer view.

Viewfilter.png



Changing Compiler versions

During project development phase it is quite common for a user to want to build their project with different versions of TI compilers. One reason may be to avail of bug fixes and new features in newer versions of compilers than those included with CCS, another reason may be to stay locked down in an older version of the compiler than the one in CCS. CCS is very flexible in allowing you to do this.

To view the current version of compiler used for the project build, right-click on the project in the Project Explorer view and go to Properties->General->Main tab, and view the Compiler version field. Note that in some cases there may be Compiler version and Effective compiler version fields. The Effective compiler version field is the version of compiler tools being used for that build (this defaults to the newest version detected by CCS). If the project was originally created with a version of compiler tools different than what is installed in your machine or what CCS is set to use, then Compiler version field will list that value.

The drop-down menu in the Compiler version field will show the different versions available if there is more than one version detected/recognized by CCS.

If you want to install a different version of compiler tools and have CCS detect/recognize it, there are a couple of ways to do it.
To install different versions, you can:

  • Install compiler tools using Help->Check for Updates (finds only newer versions), or Help->Install new Software (finds older versions as well and is the recommended method) ( a youtube video that shows the process is here)
    In this case, CCS will automatically recognize the compiler tools and show it in the drop-down menu under Compiler version.
  • Install compiler tools using a separate stand-alone installer (download from this page) or use an exisiting installation of compiler tools
    In this case, CCS can be made to detect it by:
    • following steps here: Compiler_Installation_and_Selection#CCSv5 or
    • browsing directly to it. Next to the Compiler version field select More…, enable Select new build-tool from file-system and use the Browse button to select another installation of the compiler tools.

NEW IN CCSv6: In CCSv6 and higher, the above two methods can still be used to install different compiler versions. In addition, the latest available compiler version can be obtained through the CCS App Center (menu View->CCS App Center).

To better understand how compiler updates work from within CCS, please see this page: Compiler Updates

To confirm which versions of compiler tools are discovered/known to CCS, go to menu Window->Preferences->Code Composer Studio->Build->Compilers, and check the versions listed under Discovered tools.

Note: Under Tool discovery path there are some paths that are always “discovered” by default (typically the folder where CCS was installed).
Discovery paths added by the user (not the default paths) are stored in metadata information in the file <CCS INSTALL DIR>\ccsv6\eclipse\configuration\ccs.properties

Cgt discovered.png

Once a different version is "discovered" by CCS, it will appear and can be selected from the drop-down menu in the Compiler version field. The version selected in this field will be the version used for building the project.

Compiler versions.png

Here is a short video clip that shows how to change the version of compiler tools used to build a project:






Changing SYSBIOS/XDCtools versions

Similar to changing the version of compiler tools, you can also change the version of XDCtools used to build a SYS/BIOS project.

To view the current version of XDCtools used for the build and other RTSC details, right-click on the project and go to Properties->General->RTSC tab. This tab displays the version of XDCtools used for the build, and Products and Repositories available and enabled, among other things.

The drop-down menu under XDCtools will show the different versions available if there is more than one version detected/recognized by CCS.

To install different versions of XDCtools or Products such as SYS/BIOS, you can:

  • Install using a separate stand-alone installer from the Target Content download page:


If it is installed within the main CCS installation folder, it will be automatically detected by CCS the next time it is started.
If it is installed in a different location, CCS can be made to detect it by:

  • following the steps similar to above for the compiler toolset: Compiler_Installation_and_Selection#CCStudio_5, but by going to Window->Preferences->Code Composer Studio->RTSC Products instead, or
  • browsing directly to it
    • Next to the XDCtools version field select More…, enable Select new build-tool from file-system and use the Browse button to select another installation of the XDCtools
    • Under Products and Repositories tab, select Add..., enable Select repository from file-system and use the Browse button to select the location of another repository

NEW IN CCSv6: Concurrent with the CCS 6.0.0 release, the latest release of SYS/BIOS (6.40.0) is being made available as part of the TI-RTOS product. TI-RTOS includes SYS/BIOS, peripheral drivers, and communication stacks often used in modern embedded applications. If you are a new user, it is recommended that you install TI-RTOS from the

  • CCS App Center (menu View->CCS App Center) for CCS 6.1.3 and lower
  • Resource Explorer (menu View->Resource Explorer) for CCS 6.2 and higher

If, on the other hand, you need to develop using legacy (pre-6.40.0) releases of SYS/BIOS within CCS6, the above method (stand-alone installer) can still be used to install different version of SYS/BIOS, but some additional setup/installation steps may be necessary. Please see SYS/BIOS_CCS6_Migration_Guide for additional details.

To confirm which versions of RTSC tools are discovered/known to CCS, go to menu Window->Preferences->Code Composer Studio->RTSC->Products, and check the versions listed under Discovered tools.

Note: Under Tool discovery path there are some paths that are always “discovered” by default.

Rtsc discovered.png

Once additional Products and Repositories have been detected, you can enable which version to use in your project from the drop-down menu for XDCtools version (for XDCtools) and from the Products and Repositories tab.

Rtsc versions.png



Build Configurations

During development, it is quite common to have the need to create a single project that builds executables (.out files) with different project options, source files or even for different memory configurations. In CCS this is done with Project Build Configurations.

When a new project is created in CCS, two build configurations are created by default: Debug and Release. The Debug build configuration usually has no optimization and full symbolic debug enabled, to enable easy debugging. The Release build configuration will often have optimization enabled and symbolic debug disabled, to get your code as small or fast as possible without the need for source level debug. These are just the options usually set for the default build configurations, it could be different for different device families, so it is best to check the default options set for each build configuration and tweak it as necessary.

Since the Debug configuration is what comes up by default in CCS (both when creating a new project and when importing a project) users usually start tweaking the Debug configuration directly when they are ready to start optimizing their code or modifying other compiler and linker options. Instead it would be advisable to switch to the Release configuration when you are ready to optimize your code. That way you can easily switch back to a known good debuggable configuration quickly whenever needed.
To switch the active configuration, right-click on the project, go to Build Configurations->Set Active and select the desired configuration.

Apart from the default configurations it is also possible to create and manage your own configurations.
To do so, right-click on the project and go to Build Configurations->Manage. From here you can delete, rename and create new configurations. When creating a new configuration there are several options available to copy a base set of options/settings.

Many TI examples use this feature to set up different configurations within the same project. For example, for F28xx devices, there can be RAM and Flash configurations, where one is set up to run from RAM and the other to run from Flash. Based on the configuration, the project may use a different linker command fle and may or may not include certain source files.

See the Project Build Configurations wiki page for a tutorial video that shows the procedure to create and use a project with multiple build configurations.


To build all the build configurations of a project, right-click on the project, go to Build Configurations and select Build All.



Troubleshooting common build errors

When you build a project in CCS you may encounter errors or warnings. The page below discusses some of the more common build errors and warnings.

Build Errors in CCS

Creating and Building CCS projects from command line

CCS has several terminal commands you can use to create, build, and import projects. This can be very convenient for nightly automated builds, or if you simply wish to perform these actions without bringing up the GUI interface.

Please refer to the topic below for details on all the supported commands and their usage.

Projects - Command Line Build/Create

Portable Projects

The structure of a project is important when there is a need to share a project with another user or you want to facilitate having multiple users working on the same project at the same time. Here we will consider the most common use cases for sharing projects.

  • Sharing "simple" projects or "linked file" projects
    Use this method if you wish to share the project folder and all needed source files to build the project. The source files can be either fully contained within the project folder or linked to the project. See the page below to learn how to share such projects.
Project Sharing
  • Sharing only project folder of "linked file" projects
    Use this method if you wish to share the project folder only. It is assumed that the person receiving the project already has their own copy or access to the source files. This is a common use-case for projects maintained in source control. In this case, the project should be made portable so it can be easily shared among multiple users. The key to portable projects is to avoid absolute paths. Creating portable projects involves the use of variables - linked resource path variables and build variables. See the pages below to learn more about these variables and how to create portable projects.
Portable Projects
Portable Projects Training Module

Portability across Windows and Linux

In addition to creating projects without any absolute paths, other things to consider if the project needs to be portable across Windows and Linux OS:

  • Use forward slashes in all settings and options
  • Avoid upper/lowercase characters in file names, as Windows does not differentiate between them but Linux does.

FAQs

The page below has FAQs related to projects and builds in CCS.

CCSv7 FAQs



Working with source control

The page below has information on working with source control in CCS.

Source control with CCS

Understanding tools versioning

The Code Composer Studio toolset consists of several components such as the Compiler tools, SYS/BIOS, XDCtools and so on. It is important to understand that each component has its own version number and updates for each component may be released independent of a CCS release.

For example, CCS 5.3 includes the following:

  • C6000 compiler tools version 7.4.1
  • SYS/BIOS version 6.34.02.18
  • XDCtools version 3.24.05.48

You can install updates to each of these components individually while still working with CCS 5.3.
For instance, compiler updates can be obtained and installed from menu Help->Check for Updates.
Target Content updates can be downloaded and installed from here.

So it is easy to "drop-in" different versions of these components without changing the version of CCS. It is also easy to then modify your project to build with one of these different versions of compiler tools or RTSC tools.

When reporting an issue to TI, please be sure to not only include the version of CCS, but also the version of Compiler tools, SYS/BIOS, XDCtools, or any other relevant components depending on the issue.

  • The Compiler version will be listed under Project->Properties->General->Main tab.
  • If it is a RTSC project, the versions of target content components will be listed under Project->Properties->General->RTSC tab.
  • Versions of other relevant components, such as emulation, can be found under menu Help->About Code Composer Studio->Installation Details.