<
# Introduction
A Code Composer Studio project for embedded applications contains source files and other inputs and generates an output executable file or library. A typical project consists of source files (C/C++/assembly), linker command file and a runtime support library. A TI-RTOS or SYS/BIOS project will additionally contain a BIOS configuration file. After the build process, an output executable file is created. In most cases a linker map file is also generated by default. Depending on the project settings and options, other output files may be optionally generated. This page describes some of these files and their significance.
For more information on the build flow itself, please refer to this [Project Build](https://software-dl.ti.com/ccs/esd/documents/users_guide/ccs_project-management.html#main-build) page.
# Default Files
When a new CCS project is created using the New Project wizard (menu **File → New → CCS Project**) some files are typically added to the project by default. These files vary based on the type of project (BIOS or non-BIOS), the Template chosen, and whether or not a Connection is specified. This is done merely to simplify the process for the user by adding some of the basic files required for building a program and loading it to the TI device.
One file that remains common no matter the type of project is the target configuration file (.ccxml). In CCS 5.3 and later, if a Connection is selected when creating the CCS project, a target configuration file (.ccxml) is added inside a folder named “targetConfigs”. The target configuration file defines the emulator connection and type of device it is connecting to. The creation of this file enables you to quickly start your debug session by the simple click of a button once you have built your project. This file is not used during the build process but comes into play when the program is ready to be loaded on to the target.
# Linker Command Files
When a new non-RTSC project is created, usually a linker command file (.cmd) and source file(s) (depending on the Template chosen) is added to the project. You may choose to keep the source file or delete it and add your own source files.
The linker command file is a default file chosen based on the device selected for the project. The setting that allows this default linker command file to be added is under **Tool-chain** in the New Project wizard. If the **Linker command file** field is set to *<automatic>* then the default file will be chosen. If you do not want a default linker command file chosen for you and would rather add a file of your own choice to the project, you can set the Linker command file field to *<none>*. Alternately, you can click on **Browse** and select a linker command file of your choice.
The linker command file is used during the link stage of the application build where the linker combines object files and allocates sections into the target system's configured memory. The linker command file is an ASCII file that uses two linker directives, MEMORY and SECTIONS, to allocate sections into specific areas of memory. The MEMORY directive defines target memory configuration. The SECTIONS directive controls how sections are built and allocated. In addition, the linker command file can also include input filenames and linker options.
The [Linker Command File Primer](sdto_cgt_Linker-Command-File-Primer.html) page covers the basics of linker command files, focusing on the MEMORY and SECTIONS directives.
Full details on linker command files can be found in the "Linker" chapter of the [Assembly Language Tools Users Guides](https://www.ti.com/tool/ti-cgt).
Linker command files play an important role in an embedded program as they specify where code and data sections get allocated into target memory. Without this file, the linker will not know the target memory configuration and how to properly allocate the sections. It will use default properties when allocating the sections of code. This may result in **Data Verification** errors or **Trouble Writing Memory Block** types of errors when loading code to the target. In some cases, it may still load without errors (for example, if loading to certain simulators) but it is never good practice, and will often cause the program to not work as expected when run on a target device. Hence it is very important to use a correct linker command file for your target.
To minimize load time and run time errors that may arise due to missing linker command files, the New Project wizard (in CCS 5.2 and higher) adds a default linker command file for most devices/boards. The default file should work for most simple applications, however as application requirements get more stringent, the linker command file can be customized as needed. Also, if you already have a custom linker command file to use in your application, the default one added by CCS can simply be deleted.
# SysConfig Configuration Files
[SysConfig](https://www.ti.com/tool/SYSCONFIG) is a tool for configuring pins, peripherals, radios, subsystems and software components. A .syscfg stores the configuraiton settings for SysConfig. Double-clicking on this file will open it in the SysConfig editor. The file is also used by the SysConfig command line tool when the project is built. The output of SysConfig is typically C source files that are used as part of the project build.
# TI-RTOS or SYS/BIOS Configuration Files
When a new SYS/BIOS CCS project is created, usually a configuration file(.cfg) and source files(s) (depending on the template chosen) is added to the project. In this case, the target memory definition and section allocation is generally performed by a RTSC platform file that is selected by the user during project creation.
Note: An exception is for MCU devices (TM4C, C2000, MSP430), where although a platform file is selected, the memory definition and section allocation come exclusively from a linker command file(.cmd) instead of the platform file.
A more common use-case is to begin with a TI example project provided with a SimpleLink SDK, TI-RTOS or SYS/BIOS package. In this case the project comes with a BIOS kernel configuration file (.cfg) which sets up BIOS objects and features required for the application, and all required source files. A RTSC Platform and Target are also already chosen based on the target device.
When a SYS/BIOS project is built, the XDCtools take in the platform and configuration files and auto-generates these files:
- compiler.opt: contains a set of options (typically include options and preprocessor defines) to be passed to the compiler when compiling user source files
- linker.cmd: linker command file to be passed to the linker when linking the application
The process is also shown in this [build flow-chart](https://software-dl.ti.com/ccs/esd/documents/users_guide/ccs_project-management.html#main-build).
These files can be found in the \configPkg directory within the active build configuration directory, for example, `<project_root>\Debug\configPkg` directory.
In spite of the fact that a linker command file is auto-generated by SYS/BIOS, it is still possible for a user to additionally supply their own custom linker command file, if they have additional custom sections to allocate or if they wish to allocate one of the standard sections to a different memory region than the default. For more details and examples please refer to the following page: [Memory Management](http://rtsc.eclipse.org/docs-tip/Memory_Management).
If you wish to change the default target memory definition (for example, when moving from a TI evaluation board to a custom board) you have to create a new RTSC platform since it is the platform that defines the target memory and section allocation. See the page [Demo of the RTSC Platform Wizard in CCSv4](http://rtsc.eclipse.org/docs-tip/Demo_of_the_RTSC_Platform_Wizard_in_CCSv4) for steps to create a custom RTSC platform using the RTSC platform wizard in CCS.
# Linker Map File
The linker map file (.map) is an output from the linker that provides a summary of the memory configuration, section allocation, addresses of external symbols after they have been relocated, and more. The file lists the size of code and data sections in your program and where the sections and symbols are allocated in memory. To understand the different sections generated by the compiler (.text, .bss, .const etc) and differentiate between which ones are code and which ones are data, please see the [Compiler Users Guide](https://www.ti.com/tool/ti-cgt) for the target processor you are working with.
A common misconception is that the size of the executable (.out) generated by a CCS build is an indication of the size of the program being loaded to the target. This is not true as the executable contains symbolic debug information that is not actually loaded to the target. To determine the actual size of code and data in the program, it is best to look at the linker map file.
Starting with CCSv5, a linker map file is generated by default in the active build configuration directory (\Debug by default).
To change the name or location of the linker map file, go to **Project Properties → Build → Linker → Basic Options**, and change the **--map_file** option.
For more details on the linker map file, please see the "Linker" chapter in the [Assembly Language Tools Users Guide](https://www.ti.com/tool/ti-cgt).
The **Memory Allocation view** provides a visual representation of how much memory is consumed by your application. Please see the [Memory Allocation view](ccs_memory_allocation_view.html) page for more information.
# Executable File
The executable file (.out) that is output from the build process is the file that can be loaded and executed on a target device. It can be directly loaded and debugged using CCS or can be converted to a different format, such as a hex format and programmed to the target using a hex programmer.
The executable file is typically generated in the active build configuration directory (\Debug by default).
To change the name or location of the executable file, go to **Project Properties → Build → Linker → Basic Options**, and change the **--output_file** option.
The format of the executable is either COFF or ELF. A brief history of the two formats is in this page:
[A_Brief_History_of_TI_Object_File_Formats](https://software-dl.ti.com/ccs/esd/documents/sdto_cgt_A-Brief-History-of-TI-Object-File-Formats.html)
As of CCSv8, new projects default to ELF format for C66x, MSP430 and ARM/Cortex based devices. C2000 and C5500 still default to COFF.
To check whether your project is set to create a ELF or COFF executable, right-click on the project and go to ** Properties → General → Advanced Settings**. The **Output format** field will show the format. For devices that support both ELF and COFF it is possible to change the **Output format** setting. However, keep in mind that all object files and libraries being linked together should be of the same format. For example, if you are working with ELF, all libraries linked into the project should also be in ELF format. If not there will be an error at link time and an executable will not be created.
You may hear the terms ELF and EABI used interchangeably. While ELF is the file format, EABI (which stands for Embedded Application Binary Interface) is the set of rules followed by the compiler to create a cohesive executable.
# Runtime Support Library
The runtime support is a ANSI C/C++ standard library that takes care of system startup, provides support functions for things like string handling, input/output processing, and memory allocation among other things. Since these things are handled by the runtime support library, CCS projects should link in this library.
The compiler toolset comes with a set of prebuilt runtime support libraries. Since the library can be built with an explicit set of options (to denote device, endianness, abi mode etc) that can lead to a large number of combinations, hence we only include the more commonly-used libraries in the compiler release. Take a look in the compiler release's \lib directory to see which libraries are pre-built for that particular release.
During CCS project build, if the linker requires a library that is not provided by default, it will automatically build the library as part of the project build, and place it in the \lib directory within the compiler tools installation. The library will then become available for subsequent compilations without requiring another rebuild.
Note that this library build step will cause a one-time delay when it is built for the first time. Build times of 1-5 minutes have been observed and will depend on the speed and power of the host computer (number of CPUs, etc).
The runtime library can also be built manually outside of CCS using the executable mklib, which is included with the compiler tools (starting in CCS 5.1).
When you create a new CCS project, the appropriate runtime library for your device/settings will be automatically chosen. To check this, right-click on the project and go to **Properties → General → Project** tab and verify that the **Runtime support library** field is set to *<automatic>*. It is best to leave this setting to *<automatic>* and let the linker choose the library that best matches your project options. If you still want to set it to use a specific runtime library, you may do so by selecting the appropriate one from the drop-down list in the **Runtime support library** field.
<!-- End of markdown source -->
<div id="footer"></div>
]]>