Tutorial (OSX)

This tutorial will go through the basics of using CMakeBuilder in your day-to-day programming on OSX. I assume you're using Sublime Text 3, not Sublime Text 2. Open the Terminal app, and do

$ cd Documents
$ mkdir tutorial
$ cd tutorial
$ subl .

This will open the ~/Documents/tutorial directory in Sublime Text. Create a new file called tutorial.sublime-project inside ~/Documents/tutorial and fill it with the following values:

{
    "folders":
    [
        {
            "path": "."
        }
    ],
    "settings":
    {
        // Empty for now.
    }
}

Now, close Sublime again, and in Terminal, do the following:

$ subl tutorial.sublime-project

This will open the tutorial project that we just created. It's important for Sublime to be in "project mode" in order for CMakeBuilder to work. Before, we were in "folder mode"; there was no active project. Let's say we want to create a library called awesome that will add numbers together. We want to use the awesome library in an executable called hello. Let's first create the necessary files:

~/Documents/tutorial:
  - awesome.hpp
  - awesome.cpp
  - main.cpp
  - tutorial.sublime.project

In awesome.hpp, write the following:

#pragma once

namespace awesome {

/** \brief will add two numbers together and return the result */
int add(const int x, const int y);

} // namespace awesome

In awesome.cpp, we write the implementation of the awesome::add function:

#include "awesome.hpp"

using namespace awesome;

int add(const int x, const int y)
{
    return x + y;
}

Inside main.cpp, we want to use the awesome headers to utilize our sophisticated awesome::add function:

#include "awesome.hpp"
#include <iostream>
#include <cstdlib>

int main(int argc, const char** argv)
{
    if (argc < 3)
    {
        std::cerr << "Usage: " << argv[0] << " firstnumber secondnumber\n";
        return EXIT_FAILURE;
    }
    const int x = std::atoi(argv[1]);
    const int y = std::atoi(argv[2]);
    const int result = awesome::add(x, y);
    std::cout << result << '\n';
    return EXIT_SUCCESS;
}

Now we have to bring everything together. Let's create a CMakeLists.txt in the project root:

~/Documents/tutorial:
  - CMakeLists.txt
  - awesome.hpp
  - awesome.cpp
  - main.cpp
  - tutorial.sublime.project

In CMakeLists.txt, write the following:

cmake_minimum_required(VERSION 3.0)
project(the-awesome-proj VERSION 0.1.0 LANGUAGES CXX)
add_library(awesome awesome.cpp)
add_executable(hello main.cpp)
target_link_libraries(hello PRIVATE awesome)

To enable CMakeBuilder, let's change tutorial.sublime-project:

 {
+    "cmake":
+    {
+        "build_folder": "${project_path}/build"
+    }
     "folders":
     [
         {
             "path": "."
         }
     ],
     "settings":
     {
         // Empty for now.
     }
 }

Here, if a line starts with +, it means that that line is added in comparison to what we had before. Now we are ready to use CMakeBuilder. Open the Command Palette and run the command

CMakeBuilder: Configure

If this command is not present, run the command

CMakeBuilder: Diagnose (What Should I Do?)

to see if anything is faulty. Running the Configure command will open an output panel in Sublime Text with some minimal syntax highlighting. You'll see CMake configuring the project that we defined in the CMakeLists.txt file. The build artefacts will be written to the build folder that we defined in the project file. Once configuring has completed, you can run the command

CMakeBuilder: Write Build Targets to Sublime Project File

This will create a new Sublime Build System in your project file. Check it out! CMakeBuilder will automatically select that new Build System for you, so you can continue by pressing CTRLB on the keyboard to start building the project. You will be presented with all possible targets that your CMakeLists.txt defines.