ProjectSpecs in CCS

From Texas Instruments Wiki
Jump to: navigation, search

Introduction

ProjectSpec is a feature available since CCS 5.3 that allows creation of new projects based on a project specification. The main purpose is to allow a mechanism to provide examples or projects that are somewhat CCS version agnostic. A CCS project created using the New CCS Project wizard typically embeds some version specific information such as CGT version, RTSC version, etc. in the project files. With the projectspec file, you can provide a project specification that defines some of the project properties but the actual project will be created on the fly when the projectspec is imported.

You can think of it as similar to creating a project “template” that can define several properties for the project, including things like the device, build options, source files etc. but are not tied to a specific version of compiler or RTSC tools. The projectspec file can then be shared with other users so they can quickly create projects with those specifications.

Creating Projectspec files

The XML schema file for projectspec named projectSpec.xsd can be found in the directory
<ccs_install_dir>\ccsv6\eclipse\plugins\com.ti.ccstudio.project.templates_<version>\schema
The schema file defines the structure of the projectspec files and contains documentation on many of the attributes.

Example projectspec

Below is a simple example projectspec file named MSP_5xx_example.projectspec.

It defines the device and some build options, creates two build configurations BuildConfig1 and BuildConfig2, and copies a source file and a custom linker command file into the project. If the atttribute launchWizard is set to True, then the New Project wizard will be launched during import, thereby allowing the user to further adjust the properties of the project. This attribute is not applicable in headless mode though, so will default to False when using headless mode.

<projectSpec>
  <project 
	title="Example MSP430F5529"
	name="MSP_5xx_Example"
	device="MSP430F5529"
	configurations="BuildConfig1,BuildConfig2"
	launchWizard="False" 
	linkerCommandFile="custom_lnk.cmd"
	compilerBuildOptions="--opt_level=off"
	linkerBuildOptions="--heap_size=400" 
	description="This example creates two build configurations, copies a custom source file and linker command file to the project and sets some compiler and linker options">
    <file action="copy" path="MSP_empty.c" targetDirectory="." />
  </project>
</projectSpec>


Here is an additional example from C2000Ware

<projectSpec>
  <project
        name="adc_ex1_soc_software"
        device="TMS320F280049M"
        cgtVersion="16.9.1.LTS"
        launchWizard="False"
        linkerCommandFile=""
        >
    <configuration name="CPU1_RAM" compilerBuildOptions="--opt_level=off -I${PROJECT_ROOT}/device -I${C2000WARE_DLIB_ROOT}  -v28 -ml -mt --cla_support=cla2 --float_support=fpu32 --tmu_support=tmu0 --vcu_support=vcu0 --define=DEBUG   --diag_warning=225  --diag_suppress=10063 --display_error_number" linkerBuildOptions="--entry_point code_start --stack_size=0x400 --heap_size=0x200 --define RAM" />
    <configuration name="CPU1_FLASH" compilerBuildOptions="--opt_level=off -I${PROJECT_ROOT}/device -I${C2000WARE_DLIB_ROOT}  -v28 -ml -mt --cla_support=cla2 --float_support=fpu32 --tmu_support=tmu0 --vcu_support=vcu0 --define=DEBUG --define=_FLASH --diag_warning=225  --diag_suppress=10063 --display_error_number" linkerBuildOptions="--entry_point code_start --stack_size=0x400 --heap_size=0x200 " />
    <pathVariable name="C2000WARE_DLIB_ROOT" path="../../../driverlib/" scope="project" />
    <file action="copy" path="../../../../../device_support/f28004x/common/include/driverlib.h" targetDirectory="device" />
    <file action="copy" path="../../../../../device_support/f28004x/common/include/device.h" targetDirectory="device" />
    <file action="copy" path="../../../../../device_support/f28004x/common/source/device.c" targetDirectory="device" />
    <file action="copy" path="../../../../../device_support/f28004x/common/source/f28004x_codestartbranch.asm" targetDirectory="device" />
    <file action="copy" path="../../../../../device_support/f28004x/common/targetConfigs/TMS320F280049M.ccxml" targetDirectory="targetConfigs" />
    <file action="copy" path="../../../../../device_support/f28004x/common/cmd/28004x_generic_ram_lnk.cmd" targetDirectory="" applicableConfigurations="CPU1_RAM" />
    <file action="copy" path="../../../../../device_support/f28004x/common/cmd/28004x_generic_flash_lnk.cmd" targetDirectory="" applicableConfigurations="CPU1_FLASH" />
    <file action="copy" path="../../../driverlib/ccs/Debug/driverlib.lib" targetDirectory="" />
    <file action="copy" path="../../../driverlib/" targetDirectory="device" excludeFromBuild="True"/>
    <file action="copy" path="../adc_ex1_soc_software.c" targetDirectory="" />
  </project>
</projectSpec>

Notes:

  • When creating projects using projectspec files, if there is a build option that conflicts with the default option specified in the device XML file then the one from the projectspec file will override. In this example, for instance, the optimization level is set to off (which overrides the default –o0) and heap size is set to 400 (which overrides the default 160).
  • CCSv6 has a 'ignoreDefaultDeviceSettings' attribute on the <project> element. Setting this to True would ignore all the settings which are specified in the device XML file, and the projectspec can fully dictate the initial settings for the project.



Creating/Importing project using projectspec

Once the projectspec file has been created, it can be passed to the projectCreate command via command line, or can be imported using the CCS GUI.

Command line

Here is an example command line that creates a new project using the MSP_5xx_example.projectspec:

eclipsec -noSplash -data c:\workspaces\test_workspace -application com.ti.ccstudio.apps.projectCreate -ccs.projectSpec MSP_5xx_example.projectspec 

CCS GUI

Go to menu Project->Import CCS Projects and browse to the directory containing the projectspec file. The project should be detected just like a regular CCS project and you can select it for import. In this example, since the attribute launchWizard is set to True, it will launch the wizard during import, at which point the user can adjust the properties of the project if desired.


Making project appear in Resource Explorer

You can add projectspecs to TI Resource Explorer (TI Resource Explorer Classic on newer CCS releases) so they can be imported from there just like other examples.
Follow these steps to make the projectspec example appear in Resource Explorer:

  • Create an xml file named resource_explorer.xml and place it anywhere locally, the preferred location is within the provided content directory.
    For this example, I simply placed it in the same directory that contains the MSP_5xx_example.projectspec file: C:\Work\ProjectSpec\MSP430
  • Populate the resource_explorer.xml file with content. Refer to the resource_explorer.xsd schema file in the CCSv6 install directory under ccsv6/eclipse/plugins/com.ti.ccstudio.resource.explorer_<version>/schema directory for the complete specification.
Below is the content in my resource_explorer.xml
 
<?xml version="1.0" encoding="UTF-8"?>
<resource.explorer version="1.95.00.32" name="Example Projects" desc="" dir="" href="http://www.ti.com">
      <contents name="MSP430 Examples" desc="MSP430 ProjectSpec Example for MSP430F5529" dir=".">
          <content name="MSP430F5xx Example 1" desc="Example project has two build configurations, custom source file and linker command file and some custom build options" href="MSP_5xx_example.projectspec" dir=".">
            <type>projectSpec
              <attributes>
                <attribute key="project.name" value="MSP_5xx_example"/>
              </attributes>
	    </type>
    	</content>
    </contents>
</resource.explorer>
  • Next create a reference file to let CCS know where to look for this xml file. Create a file with name ProductName_1_0_0_qualifier and place it under user.home/ti/CCSExternalReferences directory.
    For this example, I created a file named msp430projectspec_1_0_0_0
  • Edit the file and add these properties:
    • product=resource_explorer
    • path=fullpath to the directory that contains the resource_explorer.xml file
    • ccs.min.ver=5.1.0 [optional]
    • ccs.max.ver=5.1.0 [optional]
Below is the content in my example msp430projectspec_1_0_0_0
product=resource_explorer
path=C:\Work\ProjectSpec\MSP430
  • Restart CCS and open TI Resource Explorer. The example should now appear under the name Example Projects. You can expand it to select the MSP430F5xx Example 1 project and import and build it directly from Resource Explorer.
    Resource explorer.png

This process can be handy if you wish to provide one or more example projectspecs with a certain set of properties that can then be used to create projects on the fly. This can be useful in creating training/workshop projects or baseline project to be used by a team of developers. Users can import the examples via Resource Explorer and proceed to customize it as needed.