Portable Projects

This page is kept here for reference only and is still relevant for legacy versions of CCS! For latest CCS versions, please refer to this link

Introduction

This topic describes in detail how to modify your project to facilitate having multiple users working on the same project at the same time. If you are interested in how to package up and send a project (including all source files) to another user, please refer to the Sharing Projects topic.

Portable Projects in CCSv4

Project Creation

CCS projects are created inside the workspace directory by default. However, it is possible to create a CCS project outside of the workspace directory (e.g. in a source controlled directory). First dialog that appears after selecting File->New->CCS Project has a check box “Use Default location”, un checking this box allows you to specify the directory where project files should reside. Additional directory with project name will not be created if non-default location is used as user is specifying exact directory for the project in this case. Follow rest of wizard steps to create a project.

Adding Source Files

CCS provides two modes of adding source files to projects. Users can add files directly to project directory or link files to a project.

Source files in the project

Adding files can be achieved by selecting “Add Files” from project context menu. Another way is to copy files directly into project directory. CCS projects automatically include all files that appear in directory where project exists, including all subdirectories. Thus an easy way of adding multiple files is to select all folders/files that currently contain sources and copy them into project directory. Alternatively, create a project at the root of directory that already contains all sources. This approach would work well when majority of sources are organized in some root directory (there maybe many subfolders that have sources but there is a single root). The downside of this approach is that all files in a directory and subdirectories are automatically included in project build. User needs to explicitly exclude files that should not be compiled. This may not be the best approach if many projects share the same sources.

Linking Files

Linking files to a project creates a link reference that refers to a file in the file system. (similar to soft links on unix / linux systems). Files may be linked to a project by selecting "Link files to project" from projects context menu. In this case actual source files exist outside the root folder of the project. This could be used to control which source files are shown in a project and/or refer to source files that should not exist in a project (e.g. when a source directory tree is complex or portion of source code is delivered as standalone package). Normal user follow requires users to specify absolute path to linked file. This is ok if the project is not shared among different users. However, it breaks if project is moved around or if source directories move around on different user’s machines. (e.g. standalone software package is installed in a different directory on another user’s machine) This can be handled by specifying Linked resource path variables. They are kind of environment variables that CCS will use to resolve linked resources. To specify a new linked resource path variable open Window->Preferences. In top left corner in "type filter text" edit box enter "linked resources", this will filter out all other options. Click on New and select a meaningful name for path variable and specify the folder where the root of your sources is located.

Automated definition of Linked Path Variables

CCS v4 provides additional support to help with automatic definition of linked resource path variables. User creating a project may additionally create a macros.ini file that defines linked resource path variables. During project import specified variables will be automatically added to workspace settings. End user importing a project does not need to perform additional steps to build the project. Linked resource path variables defined in macros.ini file accept relative paths. This may be used to have references to common source code that exists outside projects directory structure. macros.ini needs to be placed at the root of project directory. macros.ini file has following syntax:

PROJECT1_PATH_VARIABLE=../../MyCommonLib

PROJECT1_PATH_VARIABLE2=C:/ThirdPartyLibLocation/

It is recommended that linked resource path variables be a combination of project name and user defined name to minimize chances of two different projects using the same linked resources path variable. Linked resource path variables are global to workspace thus it is possible to have two different projects use the same path variable. This may be undesirable where projects are independent and have different sources.

Adding a single linked file

Last step is to add linked resources using newly defined path variable. If adding a single or two files, then easiest is to use GUI menus. Click on File->New->File, highlight the desired project, click on Advanced, then check "Link to file in the file system" click on "Variables..." and select path variable that you added in previous step and click on "Extend..." navigate to your source file and click ok and then finish.

Adding many linked Files

If you have many files to add an easier way is to right click on the project select "Link files to project", navigate to where sources are, in the dialog perform multi-select and click Open. This will add all selected files using absolute path to resolve linked files. To make this project portable we now need to replace in project file the absolute portion of the path with path variable that was defined previously. Linked files that are part of the project are listed in .project file, which exists in the root directory of the project. Project View in CCS filters these files out by default. This filter can be turned off by clicking on a triangle button pointing down in project views menu bar, click on Filters... and disable ".*" filter. You can now double click on .project file to open it in CCS editor. Alternatively, you can use your favourite text editor by navigating to the file using windows explorer. Replace absolute portion of path for all linked sources with path variable. Save .project file, close and re-open the project (options are available on context menu). Verify that file location has linked resource as its location. (right click on any linked file and select properties; type: should be set to Linked file and Location: should contain path variable).

User’s that use these type of projects would need to define path variables in Preferences to properly resolve files. Files that can not be resolved have a warning icon overlaid on top of file icon.

Specifying compiler/linker options

Last step to make project portable is to use macros to specify paths for including header files or libraries. Every project automatically defines a number of different macros that can be used in build options. To see a list of existing macros right click on project and select properties, navigate to C/C++ Build node, Macros tab contains all automatically defined macros. There are build configuration i.e. Debug/Release and Project generic macros. Using project specific macros is a bit easier as they will be automatically re-adjusted for different users, when project is imported into CCS. User may also define their own macros similarly to how linked resource path variables are defined. These macros need to be defined in global preferences (Window->Preferences->C/++->Managed Build category). Any user defined macros will need to be defined by different users once a project is imported. (similar to how linked resource path variables would need to be defined by each user).

Portable Projects in CCSv5

In CCSv5, there is now the capability to store variables within the scope of a project rather than at the workspace level, thus everything is more self-contained within the project making it easier to share with others. This eliminates the need for a macros.ini file as was required with CCSv4. The process of creating and using linked resource path variables and build variables is simpler than in CCSv4, and is described below.

Variables

To facilitate the creation of portable projects, there are two main variables to define in CCS – Path Variables and Build Variables.

Path variables specify locations in the file systems. The path to source files/resources linked to the project can then be made relative to these variables.
Build variables specify locations, strings etc. They are used in the project build options, for example, when specifying paths for header files or libraries.

Path and Build Variables can be set at the project level or workspace level. If set at the workspace level, they will apply to all projects contained in that workspace. So they only have to be set once at the workspace level. This is advantageous for projects checked into source control and to avoid contant checkouts for modifications of the project.

Adding Source Files

When adding source files to a project in CCSv5, you have the option of either copying the files into the project folder or linking/referencing them from their location outside the project folder. Prior to linking files, the Linked Resource path variables need to be set up for the project.

To create a Linked Resource path variable:

• Right click on the project's name
• Select "Properties -> Resource -> Linked Resources"
• Here you can view, add or edit the path variables for the project.
• Use the "New" button to create a new Linked Resource variable
• Path variables are usually set to a top level folder that contains sub-folders for source files, linker command files etc.
• When creating a new portable project, set the top level path variable relative to the location of the project
• Path variables can be stored at the project scope, which avoids name collisions between multiple projects.
• When a CCSv4 project with macros.ini file is imported into CCSv5, the path variables are automatically processed. In the below screenshot, the macros indicated with a red square were processed from the macro.ini file and automatically added to the project properties when the project was imported.

To add/link files to a project:

• In the Project Explorer view, right click on a project name and choose "Add Files"
• Choose files that you would like to add and click "Open"
• A dialog will pop up asking if you want to "Copy files" or "Link files"
• If you choose "Copy files" then the file will be copied to the project directory
• If you choose "Link to files" then you can choose whether to create a link relative to PROJECT_LOC (which resolves to the root folder of the current project) or to a path variable you created

You can also drag/drop files and folders into a CCSv5 project. The above dialog will also be presented during drag/drop allowing you to choose whether to copy or link files. You can configure the action to be taken on drag/drop in the Window->Preferences->General->Workspace->Linked Resource menu or by clicking on the Configure Drag and Drop Settings in the above dialog.

Specifying compiler/linker options

While Linked Resource variables are used for linked files, Build variables are used in the project build options when specifying paths for including header files or libraries. Every project automatically defines a number of different build variables. To see a list of existing build variables, right click on project go to Properties-> C/C++ Build->Build Variables, and click on Show system variables. You may also create your own build variables similarly to how linked resource path variables are defined. To create a new build Variable use the "Add‟ button.

The build variable can then be used in the project build options.

Sharing variables file

It is possible to share the variables needed by the project by defining the needed variables to an *.ini file that a user can import.

• The file can get automatically read during a project import if:
  • the *.ini file is called ‘macros.ini’
  • the file is at the project root location

• Otherwise the file can be manually imported via File -> Import… -> Build Variables

• After import, the variable is set BOTH as a Linked Resource Path Variable and a Build Variable (despite the name of the import dialog being called just Build Variables)

• The variable is set at the workspace level

• NOTE: All variable definitions are assumed to be paths. If the definition is not a recognized path, CCS will pre-pend the path to the *.ini file for workspace level variables or the path to the current project folder for project level variables. This can be problematic for build variables that were not meant to be paths. This issue is resolved to a degree with CCSv6 by being able to specify the type for the variable in the *.ini file. See this section later in this page.

Portable Projects in CCSv6

The process of creating and working with portable projects in CCSv6 is very similar to CCSv5, so please be sure to read that section first if you are new to this topic. The main difference between v5 and v6 is described below.

Variables

Similar to CCSv5, there are two main variables of interest when working with portable projects– Path Variables and Build Variables.

Path variables specify locations in the file systems. The path to source files/resources linked to the project can then be made relative to these variables.
Build variables specify locations, strings etc. They are used in the project build options, for example, when specifying paths for header files or libraries.

Path and Build Variables can be set at the project level or workspace level.
If set at the workspace level, they will apply to all projects contained in that workspace. So they only have to be set once at the workspace level. This is advantageous for projects checked into source control and to avoid contant checkouts for modifications of the project.
If set at the project level, they will apply only to that specific project.

In CCSv5, Path variables and Build variables had to be set independently in two different places.
In CCSv6.0.x, setting a Path variable will automatically set it as a Build variable as well. Check the procedure here.
In CCSv6.1.x, the interface is further improved such that the variable can be set in one place at the workspace level and it will automatically be propogated as both Path variable and Build variable for all projects in the workspace. Check the procedure here.

To create a Linked Resource Path variable at workspace level in CCS 6.0.x:

• Go to menu Window->Preferences->General->Workspace->Linked Resources
• Here you can view, add or edit the Path variables for the workspace
• Use the "New" button to create a new Path variable
• Path variables are usually set to a top level folder that contains sub-folders for source files, linker command files etc.

This screenshot shows an example of setting a new Path variable called MYROOTPATH.

Once this variable is created, all projects in that workspace will have that variable set as both a Path variable and a Build variable. This is different than in CCSv5 where the user had to explicitly create it in two locations.

To confirm the variable is set:

• Select any one of the projects in the workspace
• Right-click and go to Properties->Resource->Linked Resources
• Observe that the variable we set earlier is shown here
• Go to Build->Variables tab, and check the box to "Show system variables"
• Observe that the variable we set earlier is shown here as well

So in summary, if you create a Path variable, the variable can be used both when linking source files as well as when specifying paths in compiler/linker options.

However, the reverse is not true. If you create a Build variable either at workspace level(Window->Preferences->C/C++->Build->Build Variables) or project level (Properties->Build->Variables tab), it cannot be used as a path variable when linking source files.

To learn more about using these variables, see the topics To add/link files to a project and Specifying compiler/linker options.

To create a variable at workspace level in CCS 6.1.x:

• Go to menu Window->Preferences->Code Composer Studio->Build->Variables
• Here you can view, add or edit variables for the workspace
• Use the "Add" button to create a new variable

This screenshot shows an example of setting a new variable called MYROOT.

Once this variable is created, all projects in that workspace will have that variable set as both a Path variable and a Build variable. This is different than in CCSv5 where the user had to explicitly create it in two locations.

To confirm the variable is set:

• Select any one of the projects in the workspace
• Right-click and go to Properties->Resource->Linked Resources
• Observe that the variable we set earlier is shown here
• Go to Build->Variables tab, and check the box to "Show system variables"
• Observe that the variable we set earlier is shown here as well

So in summary, if you create a variable at Window->Preferences->Code Composer Studio->Build->Variables, the variable can be used both when linking source files as well as when specifying paths in compiler/linker options.

However, if you create a Build variable at workspace level (from menu Window->Preferences->C/C++->Build->Build Variables) or project level (Properties->Build->Variables tab), it cannot be used as a path variable when linking source files. So the more convenient method would be to create variables from the Window->Preferences menu.

Sharing variables file

Variables file support is mostly the same as mentioned above for CCSv5. However, one key update in CCSv6 is that you can specify a string type for the variable. This is useful to override the behavior of all variables defaulting to a directory type as described above for CCSv5. To specify a variable as a string type, just prepend the variable definition with [string].

Example:

[string] VAR = VALUE

Portable target and debug configurations

Target configuration files and debug configurations can be made portable by specifying their location relative to a project's path.

Target Configurations

A Target Configuration file can be linked to a project via the PROJECT_LOC path variable:

• Open the Target Configurations view (menu View --> Target Configurations)
• Right-click on the desired target configuration, point to Link File to Project and select the project that will use this specific target configuration.
• Now go to the Project Explorer view, highlight the project selected in the previous step and open the Linked Resources --> tab Linked Resources as shown in the previous section. The target configuration should be shown there.
• Highlight the target configuration and simply click on the Convert... button. After a few confirmation screens, the path to the target configuration will be automatically changed to a relative path to the Path variable PROJECT_LOC. Click OK to accept all changes.

Note: currently this method does not work for Linux and Mac OS versions of CCS. In this case you can still manually edit the linked path.

Debug Configurations

Debug Configurations parameters can also be linked to a project in a portable way.

Open the debug configuration (reference here) and pass the following parameters to the fields:

• For the *.out file, set the option at tab Program --> option Program as ${build_artifact:nameofmyproject}

This will pick up the out file in the configuration subdirectory of the active configuration of the project

• For the *.ccxml, set the option at tab Main --> option Target Configuration as ${target_config_active_default:nameofmyproject}

This will pick up the active target configuration file of the active configuration.

Note: Project level variables like ${ProjName} are NOT supported in the debug configuration