Search in book...
Toggle Font Controls
Create new playlist

Name your new playlist

Playlist description (optional)
Sign In

Email address

Password

Forgot Password?

or

Continue with Facebook

Continue with Google
Sign Up

Full Name

Email address

Confirm Email Address

Password

or

Continue with Facebook

Continue with Google

Setting up our first project with CMake

CMake is a build process management tool that works in an operating system in a compiler-independent manner. It makes use of CMakeLists.txt to build project solutions. In this section, we will learn the process of building a CMake file for our first Vulkan application. Refer to the following instructions to understand the creation of this configuration file (CMakeLists.txt):

Create an empty CMakeLists.txt file as per the specified folder structure convention, that is, chapter_3 > Sample Name > CMakeLists.txt. For the purpose of ensuring compatibility across different CMake versions, you need to specify the minimum supported version. If the current version of CMake happens to be lower than the specified one, then it will stop building the solution. The minimum supported version of CMake is specified with cmake_minimum_required. The following is the code from the CMakeList.txt file:
```
      cmake_minimum_required(VERSION 3.7.1)
```
Specify the necessary variables that will be used to locate the path of the Vulkan SDK using the set CMake keyword. Also, provide a meaningful name:
```
      set (Recipe_Name "3_0_DeviceHandshake")
```

In this title we used CMake version 3.7.1 since it comes with a Vulkan module. This module is helpful to auto locate the Vulkan SDK installation, included directories and required libraries to build Vulkan application. In the following CMake code we first try to locate the Vulkan SDK using CMake Vulkan module, if this is unsuccessful then we use manually specify the Vulkan SDK path. Follow the given inline comment in the code for detailed description:

      # AUTO_LOCATE_VULKAN - accepted value ON or OFF

      # ON  - Use CMake to auto locate the Vulkan SDK.

      # OFF - Vulkan SDK path can be specified manually. 

      # This is helpful to test the build on various Vulkan version.
      option(AUTO_LOCATE_VULKAN "AUTO_LOCATE_VULKAN" ON )

      if(AUTO_LOCATE_VULKAN)

          message(STATUS "Attempting auto locate Vulkan using CMake......")
 

          # Find Vulkan Path using CMake's Vulkan Module

          # This will return Boolean 'Vulkan_FOUND' indicating 

          # the status of find as success(ON) or fail(OFF).

          # Include directory path - 'Vulkan_INCLUDE_DIRS' 

          # and 'Vulkan_LIBRARY' with required libraries.
          find_package(Vulkan)

          # Try extracting VulkanSDK path from ${Vulkan_INCLUDE_DIRS}
          if (NOT ${Vulkan_INCLUDE_DIRS} STREQUAL "")
              set(VULKAN_PATH ${Vulkan_INCLUDE_DIRS})
              STRING(REGEX REPLACE "/Include" "" VULKAN_PATH 
              ${VULKAN_PATH})
          endif()

          if(NOT Vulkan_FOUND)
          # CMake may fail to locate the libraries but could be able to 

          # provide some path in Vulkan SDK include directory variable

          # 'Vulkan_INCLUDE_DIRS', try to extract path from this.

 
          message(STATUS "Failed to locate Vulkan SDK, retrying again...")

          # Check if Vulkan path is valid, if not switch to manual mode.
             if(EXISTS "${VULKAN_PATH}")
                message(STATUS "Successfully located the
                                Vulkan SDK: ${VULKAN_PATH}")
             else()
                message("Error: Unable to locate Vulkan SDK. Please
                                turn off auto locate option by
                                specifying 'AUTO_LOCATE_VULKAN' as 'OFF'")
                message("and specify manually path using 'VULKAN_SDK'
                         and 'VULKAN_VERSION' variables
                         in the CMakeLists.txt.")
                      return()
             endif()

          endif()

      else()

          message(STATUS "Attempting to locate Vulkan SDK
                        using manual path......")
          set(VULKAN_SDK "C:/VulkanSDK")
          set(VULKAN_VERSION "1.0.33.0")
          set(VULKAN_PATH "${VULKAN_SDK}/${VULKAN_VERSION}")
          message(STATUS "Using manual specified path: ${VULKAN_PATH}")

          # Check if manual set path exists
          if(NOT EXISTS "${VULKAN_PATH}")
           message("Error: Unable to locate this Vulkan SDK path 
           VULKAN_PATH:
           ${VULKAN_PATH}, please specify correct path.
           For more information on correct installation process,
           please refer to subsection 'Getting started with
           Lunar-G SDK' and 'Setting up first project with CMake'
           in Chapter 3, 'Shaking hands with the device' in this
           book 'Learning Vulkan', ISBN - 9781786469809.")
              return()
          endif()

      endif()

With project keyword you can specify any desire name of your project. On Windows, Window System Integration (WSI) needs the VK_KHR_WIN32_SURFACE_EXTENSION_NAME extension API. For this, you need to define the VK_USE_PLATFORM_WIN32_KHR preprocessor directives (with -D prefixed) in the CMake file using add_definitions(). Include the path where Vulkan header files are placed. Also, add the path of the Bin folder to link the necessary Vulkan runtime/static libraries:
```
      # Specify a suitable project name
      project(${Recipe_Name})

      # Add preprocessor definitions here
      add_definitions(-DVK_USE_PLATFORM_WIN32_KHR)
```

Specify all required libraries in the VULKAN_LIB_LINK_LIST variable and later linked it to the building project using target_link_libraries(). In addition, provide a correct path for including Vulkan header files using CMake’s include_directories() API. Also, specify the path from where linked libraries are located using link_directories() API.

      # Add ‘vulkan-1’ library for build Vulkan application.
      set(VULKAN_LINK_LIST "vulkan-1")

      if(${CMAKE_SYSTEM_NAME} MATCHES "Windows")

             # Include Vulkan header files from Vulkan SDK
              include_directories(AFTER ${VULKAN_PATH}/Include)

             # Link directory for vulkan-1
              link_directories(${VULKAN_PATH}/Bin)

      endif()

The following code is used to group the header and source files together in the build source project for better visualization and management of the code structure:

      # Bunch the header and source files together
      if (WIN32)
          source_group ("include" REGULAR_EXPRESSION "include/*")
          source_group ("source"  REGULAR_EXPRESSION "source/*")
      endif (WIN32)

Specify the sample's header file path. Read all the header files and source files in the sample using file() API and store them in the CPP_Lists and HPP_Lists variables. Use these lists to specify to the build solution all the files that need to be used for compilation. Provide a name to the project build and link it to all the necessary Vulkan libraries:

      # Define include path
      include_directories (${CMAKE_CURRENT_SOURCE_DIR}/include)

      # Gather list of header and source files for compilation
      file (GLOB_RECURSE CPP_FILES
                        ${CMAKE_CURRENT_SOURCE_DIR}/source/*.cpp)
      file (GLOB_RECURSE HPP_FILES
                        ${CMAKE_CURRENT_SOURCE_DIR}/include/*.*)

      # Build project, provide name and include files to be compiled
      add_executable (${Recipe_Name} ${CPP_FILES} ${HPP_FILES})

      # Link the debug and release libraries to the project
      target_link_libraries (${Recipe_Name}${VULKAN_LIB_LIST})

Define the project properties and the correct C/C++ standard versions to be used in the project compilation. Specify the path of the binary executable:

      # Define project properties
      set_property(TARGET ${Recipe_Name} PROPERTY RUNTIME_OUTPUT_-
           DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/binaries)
      set_property(TARGET ${Recipe_Name} PROPERTY RUNTIME_OUTPUT_-
           DIRECTORY_DEBUG ${CMAKE_CURRENT_SOURCE_DIR}/binaries)
      set_property(TARGET ${Recipe_Name} PROPERTY RUNTIME_OUTPUT_-
           DIRECTORY_RELEASE ${CMAKE_CURRENT_SOURCE_DIR}/binaries)
      set_property(TARGET ${Recipe_Name} PROPERTY RUNTIME_OUTPUT_-
           DIRECTORY_MINSIZEREL ${CMAKE_CURRENT_SOURCE_DIR}/binaries)
      set_property(TARGET ${Recipe_Name} PROPERTY RUNTIME_OUTPUT_-
           DIRECTORY_RELWITHDEBINFO ${CMAKE_CURRENT_SOURCE_DIR}/binaries)

      # Define C++ version to be used for building the project
      set_property(TARGET ${Recipe_Name} PROPERTY CXX_STANDARD 11)
      set_property(TARGET ${Recipe_Name} PROPERTY
                              CXX_STANDARD_REQUIRED ON)
      
      # Define C version to be used for building the project
      set_property(TARGET ${Recipe_Name} PROPERTY C_STANDARD 99)
      set_property(TARGET ${Recipe_Name} PROPERTY
                                 C_STANDARD_REQUIRED ON)

How to build the CMake file

Follow these steps to build the CMake file:

Open the command-line terminal and go to the sample's build directory. If it is not present, create it. This empty build folder will contain the Visual Studio project built through the command line. You can also use the CMake GUI instead.
Execute the following command to build the project (choose the correct IDE version). The last parameter specifies the platform architecture; therefore, if you are using a 32-bit machine, use Win32:
```
      cmake -G "Visual Studio 14 2015 Win64" ..
```

This is how the command-line interface looks:

The two dots at the end of the command specify the path of CMakeLists.txt (one folder level up), which is required by the CMake command to build the project. Upon successful execution, you will find the following project files based on the project name specified:

The following diagram shows the folder structure of all the samples that follow in this book:

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.

Table of Contents for Setting up our first project with CMake

Create new playlist

Sign In

Sign Up

Setting up our first project with CMake

How to build the CMake file

Table of Contents for
Setting up our first project with CMake