Getting Started: Windows

Getting Started with Atlas Windows 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.
• Visual Studio (I recommend the Community version. Atlas supports VS Community 2013, 2015, and 2017), download here.

When downloading and installing Visual Studio, make sure that you select the C++ component so you have all the required compilers.

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.

1. Open the GUI and under "Where is the source code" enter the path to your project.
2. Under "Where to build binaries" enter the same path but add "/build" at the end.
3. Click on "Configure". It will ask you if you want to create the build folder. Click yes.
4. Choose the generator. Make sure that the current version of Visual Studio that you're using is selected (should be by default) and "OK".
5. Assuming that there are no errors, click "Generate".
6. Finally click on "Open Project" or go to test/build and open the test.sln file.

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.