Skip to content

Building CBA from source

Jump to bottom
jonpas edited this page Aug 4, 2019 · 9 revisions

This page describes how you can setup your development environment for CBA, allowing you to properly build CBA and utilize file patching.

Requirements

  • Arma 3
  • Arma 3 Tools (available on Steam)
  • P-drive
  • Run Arma 3 and Arma 3 Tools directly from Steam once to install registry entries (and again after every update)
  • Python 3.x
  • Mikero Tools: DePbo, DeOgg, Rapify, MakePbo, PboProject
    • *.hpp removed from PboProject’s "Exclude From Pbo" list
    • -F rebuild RequiredAddons disabled
  • Python, Mikero Tools and Git in PATH environment variable

Why so complicated?

CBA uses macros to simplify things and give the developer access to a better debug process, which requires a stricter build environment. Additionally, Mikero’s Tools are stricter and report more errors than Addon Builder does. The structure of this development environment also allows for file patching, which is very useful for debugging.

Not offering .exes for the Python scripts we use allows us to make easy changes without the hassle of compiling self-extracting exes all the time.

Getting Source Code

To actually get the CBA source code on your machine, it is recommended that you use Git. Tutorials for this are all around the web, and it allows you to track your changes and easily update your local copy.

You can clone CBA with any Git command line client using the following command:

git clone https://github.com/CBATeam/CBA_A3.git

If you just want to create a quick and dirty build, you can also directly download the source code using the "Download ZIP" button on the front page of the GitHub repo.

Setup and Building

Initial Setup

Navigate to tools folder in command line.

cd <path-to-cloned-repository>/tools

Execute setup.py to create symbolic links to P-drive and Arma 3 directory required for building.

Should the script fail, you can create the required links manually. First, create x folders both in your Arma 3 directory and on your P-drive. Then run the following commands as admin, replacing the text in brackets with the appropriate paths:

mklink /J "[Arma 3 installation folder]\x\cba" "[location of the CBA project]"
mklink /J "P:\x\cba" "[location of the CBA project]"

Create a Test Build

To create a development build of CBA to test changes or to debug something, execute build.py in the tools folder. This will populate the addons folder with binarized PBOs. These PBOs still point to the source files in their respective folders however, which allows you to use file patching. This also means that you cannot distribute this build to others.

To start the game using this build, you can use the following modline:

-mod=x\cba

Create a Release Build

To create a complete build of CBA that you can use without the source files, execute make.py in the tools folder. This will populate the release folder with binarized PBOs that you can redistribute. These handle like those of any other mod.

File Patching

File Patching allows you to change the files in an addon while the game is running, requiring only a restart of the mission. This makes it great for debugging, as it cuts down the time required between tests. Note that this only works with PBOs created using MakePbo, which build.py uses.

To run Arma 3 with file patching add the -filePatching startup parameter.

Files must exist in the built PBOs for file patching to work. If you create a new file you must rebuild the PBO or Arma will not find it in your file paths.

Disable CBA Function Caching

By default CBA caches a compiled version of functions to reduce mission load times. This interferes with file patching. There are three ways to disable function caching:

  • Load cba_cache_disable.pbo (included in CBA’s optionals folder - simply move it to addons folder for the time being)
  • Add the following to your test mission's description.ext:
class CfgSettings {
    class CBA {
        class Caching {
            compile = 0;
            xeh = 0;
            functions = 0;
        };
    };
};
  • To only disable caching for a single module, hence greatly improving mission restart time, add the following line to the script_component.hpp file of said module:
#define DISABLE_COMPILE_CACHE

Restrictions

Configs are not patched during run time, only at load time. You do not have to rebuild a PBO to make config changes, just restart Arma. You can get around this though if you are on the dev branch of Arma 3 and running the diagnostic exe. That includes diag_mergeConfig which takes a full system path (as in p:\x\cba\addons\my_module\config.cpp) and allows you to selectively reload config files.

Clone this wiki locally