CCS News

Configuration Management with the CCS Compiler Tool Suite

Tuesday 22 December, 2020

There are many version control programs available to help keep track of software changes from one version to another as well as shared code between projects. We use a free SVN here at CCS, but there are many good free and commercial products out there. This article addresses how to best use features in the CCS compiler tool suite to augment the basic capabilities of a version control system.

One problem that frequently comes up is attempting to rebuild a project that was built years ago. This is usually done before making an update to make sure the right code is being used as a starting point. Sometimes users even have trouble getting the same build result on different PC's even using the current software. There are three considerations for getting an exact hex file from source:

1. Compiler Version
Optimization changes are made in almost every release, although the software may be functionally the same, the hex file can be different. If it is important that the hex file is identical, then including code like the following in the source will help:

#if (getenv("VERSION_STRING") != "5.045")
#error Wrong compiler version, use 5.045

Users should also archive the compiler installer for that version. If it is lost, users can always contact CCS with the reference number, compiler name (like PCW) and the version needed.

The IDE compiler allows for multiple versions to be available at the same time. Users can also fix the version for a specific project under OPTIONS > PROJECT OPTIONS so the IDE will always use that version for that project.

If there is a difference in builds between versions users can use the IDE feature TOOLS > FILE COMPARE to compare the old and new .lst files. This will identify all differences in the generated code. A review of the differences should help deciding if there is cause for concern. It is always a good idea to archive the .lst file with the source to help in this analysis. Note that the compiler version is at the top of the .lst file.

2. Include Files
It is important to use the same include files to get the same result. It is best to archive all include files used for a project, including those provided by the compiler in the version control system. This is usually the cause of a program compiling differently between two PC's. The compiler has an output file that can help users identify all the included files and the exact file being used. In the .sym file there will be a section that looks like this:

Under "Project Files" is listed every source file used to build the project along with the file date of the source file and its CRC. The files are relative paths with respect to the project directory shown above the list. This is a great help in making sure all the include files have been archived and that the same files are being used for a build. Archiving the .sym file will help in figuring out what was done.

Notice the .sym file also includes a CRC of the entire source code base and a CRC of the hex file. The CRC shown in the .sym file will match the CRC shown at the end of the .hex file. Users can open the .hex file in notepad to check it. The CCS device programmers will users if the hex file itself does not match the CRC due to a corrupted file.

3. Changes Outside the Source Code
There are a few things that can affect the generated code outside of the source code. The most obvious is compiler switches that might be included on the command line for a command line compile or from MPLAB. For example optimization level. The CCS IDE does not have code generation options as we encourage users to include such options in the source code (like: #opt 5).

Pre-processor defines can also be included on the command line or in the IDE under global defines. This is a great way to use the same code to produce different versions of the firmware. In the CCS IDE saving the .ccspjt file will have those defines saved. For command line compiles, saving the batch file that does the compiles might be enough. Users can also insert comments in the hex file to indicate what defines were used. For example:

#hexcomment\ Built with CCS PCD Compiler version __PCD__
#ifdef HAS_PTT
#hexcomment\ Built with "HAS_PTT" defined

The end of the .hex file will look like this:

; Built with CCS PCD Compiler version "5.098"
; Built with "HAS_PTT" defined
;CRC=175B CREATED="24-Nov-20 11:02"

Note that the \ puts the comments at the end of the file. Comments at the top of the file are displayed to the user each time a chip is programmed if the CCS device programmers are used. This can be helpful for example if different builds are for different products. For example:

#ifdef MAGIC_6000
#hexcomment This is for the MAGIC 6000 only
#hexcomment This is for the MAGIC 3000 only

Finally if the code uses features like __DATE__ then the generated hex might be expected to mismatch.
For example:
const char PROGRAM_ID[] = {"CLRspkr built on " __DATE__};

will cause the date of the build to be part of the hex file.

In summary when archiving the source, make sure to include all the include files listed in the .sym file. Save the .lst, .sym, .hex and .ccspjt files with the source. Use #hexcoment to insert all configurable items in the .hex file. Save the compiler installer itself for versions used for production builds.

Like us on Facebook. Follow us on Twitter.

About CCS:

CCS is a leading worldwide supplier of embedded software development tools that enable companies to develop premium products based on Microchip PIC® MCU and dsPIC® DSC devices. Complete proven tool chains from CCS include a code optimizing C compiler, application specific hardware platforms and software development kits. CCS' products accelerate development of energy saving industrial automation, wireless and wired communication, automotive, medical device and consumer product applications. Established in 1992, CCS is a Microchip Premier 3rd Party Partner. For more information, please visit

PIC® MCU, MPLAB® IDE, MPLAB® ICD2, MPLAB® ICD3 and dsPIC® are registered trademarks of Microchip Technology Inc. in the U.S. and other countries.