Portable Projects in CCSv4 for C2000

The Problem:

By default, if you create a project in CCSv4 and “Add source files” directly to the project, these source files are copied directly into your project directory. Eclipse only includes source files in a project which are located directly in the project folder.

In order to include source files outside of the project folder, files must be “linked to project” (linked resources). Another problem arises here, because Eclipse only allows absolute path names when including files external to the project folder in the project. (i.e. it does not allow relative path names from the project directory using “../../” when defining which include or source files are included in a project).

The problem with this is that the project may work on your computer, but if you give the project to someone else, unless all of their files are installed on their computer in the exact same location as those on your computer, the project will break.

The Solution:

To solve this problem, there are several enhancements specific to Code Composer Studio v4, which make “portable projects” possible.

1. Linked variables and macros – allow a user to substitute a unique variable name for all our part of a path name. (i.e. you could substitute “INSTALL_BASE” for “c:/tidcs/c28/DSP2833x/v130/” if you installed a software package at that particular root directory path on your PC, and another person might substitute “INSTALL_BASE” for “c:/MySoftware/” on his or her computer).
2. Macros.ini – This file, included in every C2000 example project folder, resolves relative paths (i.e. paths defined using ../../) into linked variables and macros. When a project is imported (not simply opened) to a workspace in CCSv4, the macros.ini file is automatically read. Then macros/linked variables in the macros.ini file are automatically generated and associated to file paths for that particular computer.
3. Linked Resources – when adding source files (i.e. .c/.asm/.cmd/.lib) to a project which are not located in the immediate project directory, they are “linked” to the project instead of “added”. By doing so, the source files may be a part of the project without having to be copied into the project folder.

The above 3 are discussed in more detail in the sections below.

Linked variables and Macros

To allow for portable projects, linked variables and macros are used to substitute a unique variable name for all our part of a path name. Then when linking source files outside of the immediate project directory to a project, the part of the path name can be replaced by the linked variable name.

To see which linked variables are defined in your workspace or to manually define new linked variables, go to “Window->Preferences” from the menu toolbar. Then in the list on the left, expand “General->Workspace->Linked Resources”.

To use linked variables for resolving path names as projects are built, make sure the “Enable linked resources checkbox” is checked (It should be enabled by default). Notice in the below figure that there is a linked resource defined which is named “INSTALLROOT_2833X_V130”, and the associated path name is “C:\tidcs\c28\DSP2833x\v130”, which happens to be the default base installation directory for the 2833x/2823x C/C++ Header Files and Peripheral Examples. If you want to manually define a new linked variable, click on the “New…” button. When the dialog box opens, enter a name for your linked variable and the path name it replaces.

If you open a .project file in one of the projects which uses the linked variable, you can see the difference between using a linked variable and not using one (See below). Notice in the first linked file example, linked variables are not used. In this case, the full path name of the file is used. In the second linked file example, “C:/tidcs/c28/DSP2833x/v130” has been replaced by the linked variable, “INSTALLROOT_2833x_V130”, which has been highlighted in RED for visibility. Then the rest of the path name is defined from the installation root directory which ahs been replaced by the linked variable.

Example 1: Linked Resource File without using Linked Variables

<linkedResources> <link> <name>DSP2833x_SysCtrl.c</name> <type>1</type> <locationURI>C:/tidcs/c28/DSP2833x/v130/DSP2833x_common/source/DSP2833x_SysCtrl.c</locationURI> </link>

Example 2: Linked Resource File using Linked Variable

<linkedResources> <link> <name>DSP2833x_SysCtrl.c</name> <type>1</type> <locationURI>INSTALLROOT_2833X_V130/DSP2833x_common/source/DSP2833x_SysCtrl.c</locationURI> </link>

The advantage to the second example is that if the software package (including all linked files) is installed to a base install directory other than “C:/tidcs/c28/DSP2833x/v130” either on the same PC or another PC, it could build fine as long as the “INSTALLROOT_2833X_V130” linked variable is associated with the new base install directory.

Using Linked Variables in #include Search Path

To use the linked variable in a project as part of the #include file directory search path, simply surround the linked variable with curly brackets and add a “$” in front. In the below figure, notice that the #include search path for one of the 2833x example projects uses the “${INSTALLROOT_2833x_V130}” linked variable as the first part of the search path for #include header files.

Macros.ini

Linked variables generated without a macros.ini file require the user to:

1. Manually modify the file path associated with any linked variables used by the project each time any of the linked files or project root directory change. Any user who copies the software to another computer will need to create the linked variable of the same name on that computer with a path to the new root install directory.
2. Specify linked variable path names in absolute paths (i.e. no relative “../ paths from a project directory).

Purpose and Usage

The purpose of the macros.ini file is to eliminate the above 2 requirements, thus making portable projects easy and effortless for a user.

If you want your project to be portable, a macros.ini file should be included in the project directory with the following syntax for any number of macros:

MACRO_NAME = RELATIVE_PATH_OF_COMMON_ROOT_FROM_PROJECT_DIRECTORY

Using the CPU Timer CCSv4 example in the C2833x C/C++ Header Files and Peripheral examples V1.30 as an example, we can assume the directory structure is as shown in the below figure, and the “cpu_timer” project folder is located in the DSP2833x_examples_ccsv4 directory. Additionally, we can assume the software package as a whole was installed at the default root installation directory, “C:/tidcs/c28/DSP2833/v130” (see figure below where “v130” is highlighted with a red box).

Notice that the “cpu_timer” project folder is in the “DSP2833x_examples_ccsv4” directory. Additionally, files linked into the project which are external to the project folder are located in the folders under the “DSP2833x_common” and “DSP2833x_headers” directories. The common root of these 3 directories, is “v130”, which happens to be 2 directory levels above the “cpu_timer” project folder, which would be specified as “../../” from “cpu_timer".

Therefore, the content of the macros.ini file in the “cpu_timer” project folder is as follows:

Notice that “INSTALLROOT_2833X_V130” is defined as “../../” from the “cpu_timer” project directory in macros.ini. Therefore, as soon as the project is opened, Code Composer Studio V4 automatically creates a linked variable called “INSTALLROOT_2833X_V130”, as defined in macros.ini, and associates the linked variable with the absolute path name: “C:/tidcs/c28/DSP2833x/v130”, which it derived from the “../..” in macros.ini based on the location of “cpu_timer”. The absolute path happens to be 2 directory levels higher than the cpu_timer project directory (as specified by “../../” in macros.ini).

Constraints

If a user on the same PC decides to copy and paste the entire software package to another location on his computer an error message will pop up (see below) because CCSv4 will try to generate the linked variable “INSTALLROOT_2833X_V130” again, but associated to a different path name. One linked variable can only be associated to one path name. Select “Yes” to overwrite the old path and use the new software path. If the user then wants to return to the software installed to the original location, the linked variable path name can be overwritten again.

If another user installs the software package to the root directory “C:/MySoftware” on his computer, instead of “C:/tidcs/c28/DSP2833x/v130”, then the linked variable created will be associated with the full path name “C:/MySoftware” instead because macros.ini resolves relative path names into absolute path names to associate to linked variables at the time the project is opened.

Define More than 1 Macro

In the event that you want to define several relative paths (i.e. some common linked files may be located in a completely different location than other linked files and therefore would require a different common root directory), it is possible to define more than 1 macro in the macros.ini file (each on separate lines).

Project Migration macros.ini Auto-Generation

When projects are migrated from CCSv3.x to CCSv4, a macros.ini file is automatically generated for each project. CCSv4 will automatically determine the common root for all files linked into the project and generate a macro/linked variable name based on the project name and relative path for macros.ini. You can also manually select your own name for the macro and enter the absolute common root directory path for all files linked in your project. In this case, CCSv4 will generate a relative path for the macros.ini file based on the location of the common root directory path you entered in relation to the project directory.

Project Migration Wizard Macro Options

1. During migration if you do not select “Use a common root for all migrated projects” (recommended when migrating a single project), then CCSv4 will automatically determine the common root directory used by all files linked into the project, and generate a macros.ini file with the relative path from the project folder. This root directory is referenced from the project directory with a path variable macro name unique to the project (for this example, EXT_ROOT__EXAMPLE_2833XCPUTIMER, based on the name of the main.c file in the project), which is used by the CCSv4 project to reference external resources.
2. If you do select “Use a common root for all migrated projects” (recommended when migrating multiple projects at once but may be used to migrate a single project as well), select a root directory under which all files referenced by the project are located.

For example, in the case of the C2833x/C2823x C/C++ Header Files and Peripheral Examples V1.30 package, the common root directory for all the files is C:/tidcs/c28/DSP2833x/v130. You would select a unique path-variable macro name (In the below figure, we used – INSTALLROOT_2833X_V130). Then fill the “Path:” with the desired common root directory (i.e. You could use “C:/tidcs/c28/DSP2833x/v130” like in the figure below, or go one level higher and use “C:/tidcs/c28/DSP2833x/” instead).

Example:

The CPU Timer example C file, Example_2833xCpuTimer.c, is located at: C:/tidcs/c28/DSP2833x/v130/DSP2833x_examples/cpu_timer/

One of the files used by the CPU Timer example, DSP2833x_CpuTimer.c, is located at: C:/tidcs/c28/DSP2833x/v130/DSP2833x_common/source/

Another file used by CPU Timer example, DSP2833x_GlobalVariableDefs.c, is located at: C:/tidcs/c28/DSP2833x/v130/DSP2833x_headers/source/

Notice that the common root directory for all these files is: “C:/tidcs/c28/DSP2833x/v130”. From the cpu_timer project directory, this root can be reached with: “../../”. Therefore, CCSv4 will generate a macros.ini file with the following content:

Linked Resources (Adding Files to Project From Outside of Project Folder)

When adding source files (i.e. .c/.asm/.cmd/.lib) to a project which are not located in the immediate project directory, they are “linked” to the project instead of “added”. By doing so, the source files may be a part of the project without having to be copied into the project folder.

To “Add” files to a project which are not in the immediate project directory and maintain project portability:

Method #1 for Linking Files to Project:

• Right-click on the project in the project window of the C/C++ Projects perspective.
• Select “Link Files to Project…”
• Then navigate to the desired files to be added.

At this point, if you open .project in the project folder, you can see that the absolute path name for the desired file was added to the project (See Example 1 below). The problem with this is that because it is an absolute path, if the file is ever moved, or if the project is copied to another computer where the file is located at a different absolute path, the project build will fail.

Example 1: Linked Resource File without using Linked Variables

<linkedResources> <link> <name>DSP2833x_SysCtrl.c</name> <type>1</type> <locationURI>C:/tidcs/c28/DSP2833x/v130/DSP2833x_common/source/DSP2833x_SysCtrl.c</locationURI> </link>

• To make the project portable, open the .project file in the project folder and globally replace the absolute path name “C:/tidcs/c28/DSP2833x/v130” with its associated linked variable name (in the case of this example, “INSTALLROOT_2833X_V130”, as shown below)

Example 2: Linked Resource File using Linked Variable

<linkedResources> <link> <name>DSP2833x_SysCtrl.c</name> <type>1</type> <locationURI>INSTALLROOT_2833X_V130/DSP2833x_common/source/DSP2833x_SysCtrl.c</locationURI> </link>

Method #2 for Linking Files to Project:

• Right-click on the project in the project window of the C/C++ Projects perspective.
• Select “New->File”.
• Click on the “Advanced>>” button to expand the window.
• Check the “Link to file in the file system” checkbox.

• Select the “Variables…” button.
• From the list, pick the linked variable associated to the path name under which the desired file can be found.
• Click on the “Extend…” button
• A window pops up which reveals all the directories underneath the linked variable path you selected. Navigate to the desired file and select “Ok”.

• The full path of the file as defined from the linked variable name appears in the box underneath “Link to file in the file system”. Select the “Finish” button. The file has now been linked to the project using the linked variable name instead of the absolute path name.

More Information on Portable Projects

For more information on portable projects, visit the Code Composer Studio v4 Wiki page link: Portable Projects