6.2. Project Files and Build System Overview

CCStudio projects use CMake with the Ninja generator to build, using the CMake and Ninja binaries bundled with CCStudio rather than any you may have installed yourself.

This section provides an overview of the project metadata files and describes what happens under the hood during a build.

6.2.1. Project Metadata

Each CCStudio project has a .ccs subdirectory, which should be checked in to source control alongside your source files. It contains:

  • project.json: Stores your project's metadata — device, project type, build configurations, source folders, and tool settings. This is the file CCStudio reads and writes when you change project settings in the Projects view.

  • One subdirectory per build configuration, each containing three generated CMake fragment files (project name and dependencies, source folders, and enabled tools/flags) and a top-level CMakeLists.txt.

The CMake fragment files are regenerated automatically whenever project.json changes, so you normally never need to look at or edit them directly. This is Managed mode, the default for new projects. If you need full manual control over the CMake fragment files, switch the project to Unmanaged mode (Switch to Unmanaged Mode in the Projects view), which sets updateMakefilesAutomatically to false in project.json.

_images/ccsvsc_project-build-system.png

Note

CCStudio projects are designed to be portable: no absolute paths are written into any of these files. A project can be committed to source control and opened on any machine where the required compiler and SDK are installed, with no path edits needed.

Tip

If you switch a project to Unmanaged mode to edit the CMake fragment files by hand, keep paths portable by using the built-in and product/SDK-defined CMake variables instead of hardcoded absolute paths, and always use forward slashes, even on Windows. Add a call to ccs_print_variable_map() anywhere in a fragment file to print all defined variables, which can help when troubleshooting a build.

6.2.2. Build Steps

When a project is built, it goes through the following steps:

  1. Validate: Confirm the project can be built — the bundled CMake/Ninja tools are present, project settings are valid, and any referenced projects are resolved.

  2. Update CMake files: Regenerate the CMake fragment files in .ccs/<build-config>/ from project.json, if needed.

  3. Build referenced projects: Any projects referenced by this project are built first, recursively.

  4. Configure: CMake generates the Ninja build files. This step only runs when needed — for example, on a clean build directory — so most rebuilds skip straight to the next step.

  5. Build: Ninja runs the build. Any pre-build steps run first, followed by the SysConfig, Compiler, Linker, Archiver, and other tools needed to produce the build output, followed by any post-build steps.

As the build runs, its output is parsed to generate the error/warning/info markers you see in the Problems view.