Setting up a project

This manual will explain how to set up your own project and link it with bs::framework. We'll explore two options:

  • Link with binaries - Either download the precompiled set of binaries or compile them yourself. Then create a project that links with the binaries. If you do not wish to compile bsf yourself, this is the best approach to follow.
  • Link with source - Grab the source code and include it as part of your own project. Requires you to go through the same steps as if you were compiling bsf from scratch, but allows you to easily recompile the framework from latest source, or due to your own modifications. If you plan on making changes to the framework, or want to frequently update to the latest version, this is the best approach.

Link with binaries

The first step is to actually get bsf binaries. You have two options:

  1. Get the precompiled set of binaries from the Download page. This is the simplest and easiest solution.
  2. Grab the source code and compile the program yourself. You can either get the latest code from the GitHub repository, or download an archived version of one of the releases from the Download page. Follow the compilation guide on the GitHub page for detailed instructions. Note that you should probably consider going with the Link with source approach if you plan on compiling bsf anyway.

Whether you downloaded precompiled binaries or compiled them yourself you should now have three folders containing the entirety of bsf:

  • bin - Contains dynamic libraries and data files
  • include - Contains public header files
  • lib - Contains shared and import libraries

For precompiled dependencies these folders will be part of the downloaded archive, and for manually compiled option they will be placed in the chosen install folder.

In order to get your project running you will need to:

  • Provide a path to the bsf's include folder to your compiler
  • Link with the bsf dynamic/shared library
  • Make sure your executable can find all the dynamic libraries and data files

We'll use CMake to create a project that will ultimately work with any major build tool (like Visual Studio, XCode or Makefiles).

CMake

CMake is a build system that allows you define a project that can then be used for building across multiple platforms and build tools. Such CMake project can be used to create a Visual Studio solution, XCode project or Unix Makefiles. bsf also comes with modules that make using bsf in your CMake project easier.

Note that CMake is fairly complex and we don't go into details about all of its syntax. There are many tutorials that do that. However our project will be pretty simple and should be easy to understand even to a newcomer to CMake.

Preparation

First create a new directory where you would like your project to live. Grab the Findbsf.cmake file from here and place it in the root of your project folder. This file will be used for helping us find bsf libraries and includes.

CMake project

In your project folder create CMakeLists.txt, and fill it out like so:

# Minimum version of CMake as required by bsf
cmake_minimum_required (VERSION 3.9.0)
# Name of your project
project (myProject)
# Add necessary compiler flags
if(CMAKE_CXX_COMPILER_ID MATCHES "Clang" OR
CMAKE_CXX_COMPILER_ID MATCHES "AppleClang" OR
CMAKE_CXX_COMPILER_ID MATCHES "GNU")
add_compile_options(-fno-rtti)
endif()
# Make sure to use the C++14 standard
set(CMAKE_CXX_STANDARD 14)
# Build an executable from the provided C++ files
add_executable(myApp "Main.cpp")
# Path to where you have installed bsf
set(bsf_INSTALL_DIR "C:/path/to/bsf/install")
# Let CMake know where to find the Findbsf.cmake file (at current folder)
set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}")
# Find bsf libraries and headers
find_package(bsf REQUIRED)
# Link bsf library with your application
target_link_libraries(myApp PRIVATE bsf)

Code

The CMake file above references Main.cpp file. The most basic file that runs the framework looks like so:

#include "BsApplication.h"
int main()
{
using namespace bs;
VideoMode videoMode(1280, 720);
Application::startUp(videoMode, "Example", false);
Application::instance().runMainLoop();
Application::shutDown();
return 0;
}

We will explain the code above in following manuals, but for now you can just copy/paste it and use it for the starting point.

Place the Main.cpp into your project's root folder.

Get CMake

If you don't already have it, grab the latest version of CMake from www.cmake.org. Make sure to grab version 3.9.0 or later.

Build

You are now ready to build the project. From your project's root folder execute the following commands in terminal/command line:

  • mkdir build
  • cd build
  • cmake -G "$generator" ..
    • Where $generator$ should be replaced with any of the supported generators. Some common ones:
      • Visual Studio 15 2017 Win64 - Visual Studio 2017 (64-bit build)
      • Unix Makefiles
      • Ninja
      • Xcode
      • See all valid generators: cmake-generators
    • If your system complains that cmake is not a valid command, you need to add the path of CMake binaries to your $PATH environment variable

Your build files will be output to the build folder.

  • If you are using Visual Studio open up the build/myProject.sln solution and proceed building as normal
  • If you are using XCode open up the project in the build folder and proceed building as normal
  • If you are using Makefiles simply run make within the build folder

Copy files

Before you can run the application you must first copy the data files and dynamic libraries so that your application can find them when it starts.

  • Copy the bin/Data folder to the location where is your executable is located
  • If on Windows you should also copy any .dll files in the bin folder to where your executable is located. Note that precompiled binaries package comes with separate set of dynamic libraries for Debug and Release builds in bin/Debug and bin/Release folders. You should copy them to the appropriate folder depending on the configuration you are building with.

For example in Visual Studio the executable will be placed at x64/Release/ within your project root, for a 64-bit Release configuration. This is where you should place the dynamic libraries and the data files.

BuildStructure.png
Structure of the executable folder on Windows

Run

You are now ready to run the application. If you used the default Main.cpp code above an empty window should open.

Link with source

This is an alternative approach to linking with binaries. bsf source code will be included as part of your own project, making sure any changes you make can easily be compiled and tested.

Preparation

First make sure to follow the compilation guide on GitHub. You only need to do the first few steps of that guide and ensure you have installed all the required dependencies, as well as checked out bsf from its repository. Actual CMake calls can be skipped at this point.

CMake project

Create a new project folder, with a CMakeLists.txt file with the following contents:

# Minimum version of CMake as required by bsf
cmake_minimum_required (VERSION 3.9.0)
# Name of your project
project (myProject)
# Let the system know where `bsf` source code is located
set(BSF_DIRECTORY "C:/bsf" CACHE STRING "bsf directory")
# Include bsf projects and their CMake code
include(${BSF_DIRECTORY}/Source/CMake/ProjectDefaults.cmake)
# Build an executable from the provided C++ files
add_executable(myApp "Main.cpp")
# Add bsf as a dependency
target_link_libraries(myApp bsf)
# Add required plugin bsf dependencies (as selected through CMake properties)
add_engine_dependencies(myApp)
# Add optional dependencies (specify all, some, or none of these as required)
add_dependencies(myApp bsfFBXImporter bsfFontImporter bsfFreeImgImporter)
# When 'myApp' target is built, copy required binaries from bsf
copyBsfBinaries(myApp ${BSF_DIRECTORY})

Code

The CMake file above references Main.cpp file. The most basic file that runs the framework looks like so:

#include "BsApplication.h"
int main()
{
using namespace bs;
VideoMode videoMode(1280, 720);
Application::startUp(videoMode, "Example", false);
Application::instance().runMainLoop();
Application::shutDown();
return 0;
}

We will explain the code above in following manuals, but for now you can just copy/paste it and use it for the starting point.

Place the Main.cpp into your project's root folder.

Build

You are now ready to build the project. From your project's root folder execute the following commands in terminal/command line:

  • mkdir build
  • cd build
  • cmake -G "$generator" ..
    • Where $generator$ should be replaced with any of the supported generators. Some common ones:
      • Visual Studio 15 2017 Win64 - Visual Studio 2017 (64-bit build)
      • Unix Makefiles
      • Ninja
      • Xcode
      • See all valid generators: cmake-generators
    • If your system complains that cmake is not a valid command, you need to add the path of CMake binaries to your $PATH environment variable

Your build files will be output to the build folder.

  • If you are using Visual Studio open up the build/myProject.sln solution and proceed building as normal
  • If you are using XCode open up the project in the build folder and proceed building as normal
  • If you are using Makefiles simply run make within the build folder

After building any executables/dynamic libraries will be placed in the bin sub-folder in your project root, and any static/shared libraries will be placed in the lib sub-folder.

Unlike with Link with binaries approach you do not need to do any file copying, until you are ready to send the application to your users. After the build the application is ready to run.