Getting Started: Linux

Getting Started with Atlas Linux/Unix Edition

Setup

Before we get started, it is important that you have all the tools required to work with Atlas. These are:

• CMake, download here or install it using your package manager.
• A C++ 14 compatible compiler (be it GNU or Clang).

Once everything is downloaded and ready to go, let's get started with our project. For the sake of simplicity, we are starting from an empty project that will be using the same folder hierarchy present in Atlas. The structure is:

project
|- source (all .cpp files go here)
|- include (all .h/.hpp files go here)
|- shader (all glsl files go here)

Let's assume that our project folder is called test. Inside, create the above directory structure and download Atlas.

Getting Atlas

If you are using git for version control, then adding atlas is very simple. The command is the following:

git submodule add https://github.com/marovira/atlas.git lib/atlas

This assumes that you are running this command at the root of your project directory (in our case test). Once you run this, type

git submodule init
git submodule update

You will notice that Atlas will be donwloaded into lib/atlas and you will have two new files to commit. Commit them and you are ready to go to the next step.

If you are not using git, then simply download the code as a zip, and extract it into lib/atlas.

CMake Setup

We are now ready to setup CMake for our project. Create the necessary folders so you end up with the same directory structure outlined above. Now, on the root of your project (test), create a new file called CMakeLists.txt and enter the following code:

project(test) # You can change test for your project name.

cmake_minimum_required(VERSION 3.0)

set(TEST_SOURCE_DIR "${PROJECT_SOURCE_DIR}") # You can name these variables whatever you like.
set(TEST_BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}")
set(TEST_ATLAS_ROOT "${TEST_SOURCE_DIR}/lib/atlas")
set(TEST_INCLUDE_ROOT "${TEST_SOURCE_DIR}/include")
set(TEST_SOURCE_ROOT "${TEST_SOURCE_DIR}/source")
set(TEST_SHADER_ROOT "${TEST_SOURCE_DIR}/shader")

add_subdirectory("${TEST_ATLAS_ROOT}") # This will add all of the Atlas files for you.

add_subdirectory("${TEST_INCLUDE_ROOT}") # Adds your header files
add_subdirectory("${TEST_SOURCE_ROOT}") # Adds your source files
add_subdirectory("${TEST_SHADER_ROOT}") # Adds your shader code.

# Adds the include directories. We also add the shader root so we can use any GLSL headers we define in C++.
include_directories(
    ${ATLAS_INCLUDE_DIRS}
    ${TEST_INCLUDE_ROOT}
    ${TEST_SHADER_ROOT}
    )

# Creates the executable.
add_executable(test ${TEST_SOURCE_LIST} ${TEST_INCLUDE_LIST} ${TEST_SHADER_LIST})
# Links the Atlas libraries.
target_link_libraries(test ${ATLAS_LIBRARIES})

Once you have the file created, the next step is to add a new CMakeLists.txt file into include, source, and shader. The files are the following:

# test/include/CMakeLists.txt
set(INCLUDE_LIST
    # Add your files here as ${TEST_INCLUDE_ROOT}/FileName.hpp
    )

# OPTIONAL! If you don't use this, just add your files directly to TEST_INCLUDE_LIST.
# Now we generate a header that contains the path to our shader directory so we can access the shaders from our code.
set(SHADER_INCLUDE "${TEST_INCLUDE_ROOT}/Paths.hpp")
configure_file("${TEST_INCLUDE_ROOT}/Paths.hpp.in" ${SHADER_INCLUDE})

set(TEST_INCLUDE_LIST
    ${INCLUDE_LIST}
    ${SHADER_INCLUDE}
    PARENT_SCOPE)

# test/source/CMakeLists.txt
set(TEST_SOURCE_LIST
    "${TEST_SOURCE_ROOT}/main.cpp" # You always need this!
    # Add the rest of your source files here.
    PARENT_SCOPE)

# test/shader/CMakeLists.txt
set(TEST_SHADER_LIST
    # Add your files here.
    PARENT_SCOPE)

With all of this done, we just need to add a main file to our source directory (it can be empty for now). After that, add the following file to include (if you are using the custom header in the include CMakeLists.txt) and save it as Paths.hpp.

#ifndef TEST_INCLUDE_PATHS_HPP

constexpr const char ShaderDirectory[] = "@TEST_SHADER_ROOT@/";

#endif

Once all of this is setup, you can run CMake. I usually recommend having a separate directory where all of the build files are located. This makes cleaning up your code easier later on. With that assumption in mind, open a command line and enter the following:

cd /path/to/project/dir
mkdir build
cd build
cmake ..

This generates a makefile that you can then use to compile and run your program. You are done! Now you can compile and run your application and everything will be properly linked. If you want to add new files, just add them to the appropriate CMakeLists.