workshop01_settingUpABuildSystem.adoc

Setting up a Build System

links.adoc

Where we want to get to

• We need to be able to use libraries for Games Programming

• For this module, we’ll mainly be using the {link-sdl2}[SDL2] library

• By the end of this session, you should have:

  • gotten our test program to run, using two different build systems

    1. manual approach

    2. automated approach (using {link-conan}[conan.io] and {link-cmake}[cmake])

  • written an automation script to fully automate that

    • e.g. a Windows .bat file

Activity summary

• Imagine you have a friend/collegue/future self that needs to develop program

• They/you will need to setup their system for this

  1. Write (through this session) instructions of how to set up for developing your program

     • write by hand or a digital document

     • make sure to give all steps, with sufficient detail

  2. Email your instructions at the end of the session

Activity summary

• There are questions scattered throughout this document.

  • Try to answer all of them.

  • Discuss them with your collegues/friends

Stages of making and running a program, and where errors can occur

• There are 3 main stages going from source code to a running program.

• This is true independent of C++

Compilation

• Compile allh *translation unit" (roughly, each source code file)

• Creates binary object files (.obj on Windows)

• COMPILE-TIME errors

Linking

• Link object files together

• Link also with any static libraries (.lib on Windows)

• Creates an executable binary (.exe on Windows)

• LINK-TIME errors

Load and Dynamic linking

• Load the program into memory (RAM, or virtual memory)

• Load any dynamic/shared libraries into memory (unless already loaded)

• update the program to reference into the in-memory dynamic libraries

• RUN-TIME errors

Types of library

1. Header-only libraries

   • just source code - EASY

2. Static libraries

   • embedded into our exe by the linker - MEDIUM

3. Dynamically-linked libraries / Shared libraries

   • linked to our exe at run-time - HARD

Setting up Header-only libraries

• Header-only libraries only contain source code.

• Our compiler will compile all this library code for us right into our program.

Setting up Header-only libraries (steps)

1. Find library header files and put somewhere on our local system

2. Use the header files (.h or .hpp) from our code

3. Tell our compiler where to look for header files to compile in

Setting up Static library

• Static libraries still have header files

  • these tell us and our compiler the interface to the library

  • what functions/variables exist

• Static libraries have pre-built binary files that will be embedded in our executable program

Setting up Static library (steps)

1. Find library header files and put somewhere on our local system

2. Use the header files (.h or .hpp) from our code

3. Tell our compiler where to look for header files to compile in

4. Tell our linker which libraries to link to

5. Tell our linker where to look for binary library files are (.lib)

Setting up Dynamic/Shared libraries

• Dynamic libraries still have header files

  • these tell us and our compiler the interface to the library

  • what functions/variables exist

• Dynamic libraries usually have an import library (.lib) files

  • tell our linker what is in the binary and where

• Dynamic library have dynamically linked binaries (.dll)

  • provide executable code to our program, loaded at run-time

Setting up Dynamic/Shared libraries (steps)

1. Find library header files and put somewhere on our local system

2. Use the header files (.h or .hpp) from our code

3. Tell our compiler where to look for header files to compile in

4. Tell our linker which libraries to link to

5. Tell our linker where to look for binary import library files are (.lib)

6. Make sure our Operating System can find the Dynamic libraries at run-time

   • on Windows, this would in the path, or in the same directory as the .exe

Activity overview

• We’ll start with a "HelloWorld!" Program, with some initial, minimal functions from SDL2 that we wish to use

• We’ll go through a series of steps to:

  1. allow our program to compile

  2. allow our program to link

  3. allow our program to run

• We’ll then repeat this using {link-conan}[conan.io] and {cmake}[cmake] to make our lives easier and more scalable

  • our program will depend on at least 3 libraries during this module

1. Create a New Visual Studio (2015)C++ solution

1. New Project

   1. Visual C++ → Win32 Console Application

   2. ANYWHERE you choose

   3. Make "Empty project"

   4. Untick "Security Development LifeCycle"

2. Add test program

1. Add a new source file named main.cpp

2. Add the contents below BY HAND - don’t copy-paste

main.cpp

link:{examplesdir}/buildSystem/main.cpp[role=include]

2.1 Read the test program

• Note the #include directives

  • this ask the compile to literally copy-paste that header into this file

  • those in angle-brackets (< or >) are System headers

• Note the function names beginning with SDL

  • these functions are from the SDL2 library (we hope/intend)

  • Your IDE (Visual Studio) is telling you something about these. What is it saying? What is the error?

• Look carefully at the function signature of the main function

3. Try to compile the program

1. Build → Build Solution (Ctrl-Shift-B)

2. What are the errors?

3.1 badly fix the errors

1. Comment all the lines which cause errors

   1. rebuild, and run (in debug) - F5

2. Does it run?

3. Can you see the output?

4. Find your exe on your system, and run it from the command line

   1. How do you start a command line???

   2. How do you change directory if your path has spaces in it??

4. Download SDL2

1. Search the web for SDL2 and try to find a download link

4.1 Which version???

1. There are a number of versions on https://www.libsdl.org/download-2.0.php

2. Which do you think you want?

   1. HINT: We are developing software

   2. HINT: What platform are we on?? and Word-size??

   3. HINT: What is our compiler suite?

3. Which version of SDL2 did you download??

   1. What is it’s version number?

5. Extract SDL2

1. Extract your download

   1. Where do you think you should you put it?

      • Your program will need to access them

      • What happens if you move your project ??

   2. How big are these files?

   3. What folders and files have you extracted?

   4. Do you think these files should be versioned along with your source code?

6. Tell Visual Studio where the headers are

1. What header file you need??

   1. What are all these other files??

2. Where in the library you’ve download is this header file?

3. How do you tell Visual Studio where header files are?

   1. Search for how to?

   2. Figuring out questions like this yourself is important.

   3. Is Visual Studio confusing on this?

4. How many clicks do you need to do in Visual Studio to do this?

   1. Think this is error prone/easy/repeatable?

6.1 Build and Run Again

1. Uncomment the #include for SDL

   • Do the Visual Studio errors (on-screen) go away

2. Does your program now build?

3. Break it down:

   1. Does it compile?

   2. Does it link?

   3. Does it run?

   4. What is missing? What do the errors say?

7. Tell Visual Studio where the .lib files are

• and which libraries to try to link to

  1. How do you tell Visual Studio where library files are?

  2. How do you tell Visual Studio which libraries to link to?

  3. How many clicks do you need to do in Visual Studio to do this?

7.1 Build and Run Again

1. Does your program now build?

2. Break it down:

   1. Does it compile?

   2. Does it link?

   3. Does it run?

   4. What is missing? What do the errors say?

8. Copy dlls to the appropriate location

1. Where does your Operating System look for Dynamic libraries by default?

2. Can you change this? Should you?

3. What else can you do?

   • HINT: see the above heading!!

8.1 Build and Run Again

1. Does your program now build?

2. Break it down:

   1. Does it compile?

   2. Does it link?

   3. Does it run?

   4. What is missing? What do the errors say?

9. So now you have a running program! ?

• Assuming you now have a running program

  1. Run your .exe from the command line

  2. Can you make it so that when you run your program from Visual Studio you can see the output?

     • HINT: there are many ways of doing this

10. That was for just one library!

1. Find a collegue/friend

   1. Go through each other instructions

   2. What did you each do the same, or differently?

   3. Do those things matter?

2. What would this be like if you had 3 libraries your project needed?

   1. or 8 libraries?

11. Another approach

• Historically, C++ hasn’t had a package manager

  • Most/Many other languages do have (good/poor) package managers

• {link-conan}[Conan.io] is pretty new

  • that’s great - makes things easier

  • that’s challenging - this change and break

    • changes, broken things is very common

    • especially in Games!!

12. Conan and Versioning

• Conan.io is pre-installed on Lab machines

  • if working at home or on a laptop, you’ll need to install it

• If you want to use a versioning system, now would be a good time to start

  • we strongly recommend the use of some kind of versioning

  • we recommend git, but other good tools exist

13. Starting afresh with {link-conan}[conan.io]

1. Make a new folder somewhere for your project

   • call it gamesProgramming or anything you like

   • you can (if you like) remove all the library files you carefully downloaded!!

2. We tell conan about the libraries we need with special file - conanfile.txt

   • conan can then go off and find these libraries for us

   • and even, build them from source if it needs to

   • and create files for us, that tell us where things are

13.1 Create your first conanfile.txt

1. Create a file name conanfile.txt in the root of your new (gamesProgramming) folder, with the following content

   • this gives conan the library name, version and who’s package to use, and the channel

   • see conanio on readthedocs for more info

conanfile.txt

link:{examplesdir}/buildSystem/conanfile.txt[role=include]

13.2 Explanation of this conanfile.txt

1. We’ve said our project requires the SDL2 library, version 2.0.4 that has been packaged by lasote and is in the stable channel

2. We’ve said the option shared on the SDL2 library is set to True

   • meaning we want a shared (dynamic) version of SDL2

   • we could go with False and embed SDL2 directly in our program

     • we shouldn’t do this

     • for good practice

     • and without checking whether the license terms of the library allow this (e.g. GPL license) - Discuss/Research

3. We’ve said we want conan to generate output for cmake

   • this output will contain details on where the needed parts of libraries are located, etc.

13.3 Build out-of-source

1. Go to your gamesProgramming folder with a console

   • we recommend gitBash on Lab machines

   • that way you can use git from the commandline also if you choose

2. Make a new directory called build

   • this is where are build files will go

   • most of these will be temporary - we don’t need to version them

   • using a separate directory keeps the build clean

13.4 Ask conan to install the libraries

1. in your console cd to build

2. run conan install .. from the build directory

   • ask conan to install packages listed in the .. (parent) directory (in conanfile.txt)

   • watch the output

   • try to figure out what conan is doing

   • what information does it tell you at the end?

13.5 What has conan created?

• Conan has created a bunch of files for us

  1. What two, separate locations has conan put files?

  2. What files has conan put in out present directory?

13.6 Where conan has put the libraries

1. Have a look at the conanbuildinfo.cmake

   • This is a file that tells cmake about file locations

   • It’s not very human readable

2. Add a generator text to your conanfile.txt and re-run the conan install command

   • Have a look a the new file - this should tell you stuff in an easier way

   • But not useful for anything except:

     • your knowledge or

     • if you had to set things up manually (you could do this in Visual Studio now, using the libraries conan has installed)

     • you can remove the text generator if you want, and clear the associated, generated file

14 Add the main.cpp

1. Add a new source file named main.cpp in the root of your project (gamesProgramming)

   • you can copy-paste this time :-)

   • don’t create this in your build folder

   • build should only contain files that can be generated

main.cpp

link:{examplesdir}/buildSystem/main.cpp[role=include]

15. Ask cmake to create a Visual Studio Solution

• {link-cmake}[cmake] is a build system builder!!

• It can make various forms of build system

• We’re interested in Visual Studio solutions

• We tell cmake what we want using a CMakeLists.txt file

  • note the capitalisation

15.1 Create a CMakeLists.txt file

1. In the root of your project folder (gamesProgramming), create a file named, exactly, CMakeLists.txt

   • with the following content

CMakeLists.txt

link:{examplesdir}/buildSystem/CMakeLists.txt[role=include]

15.2 Explanation of the CMakeLists.txt file

• The name of the solution (ConanTest)

• minimum cmake version ( 2.8.12)

• use the conanbuildinfo.cmake file we made

• run some stuff to make conan work

• make an exe called conanTest from main.cpp

• use libraries from conan for that exe conanTest

• make conanTest our startup project

15.3 Ask Cmake to create a Visual Studio Solution

1. In your build directory run the following, from the command line (gitBash)

   • note what build system we’re and platform we’re asking cmake to create for

   • the .. tell cmake to look in the parent directory for the CMakeLists.txt file

cmake .. -G "Visual Studio 14 Win64"

15.4 Use the Visual Studio solution

• Load the Visual Studio solutin (.sln) in the build directory, and build from the UI

• OR ask cmake to build (with Visual Studio’s compiler) for you

cmake --build . --config Release #ask cmake to build in Release mode

15.5 Run your new binary

• Run from Visual Studio (F5).

  • WARNING: you will likely get a console window that immediately exits

• OR run from the command line

./bin/conanTest.exe

16. Automate everything!

• We’ve only really executed 4 commands above

  • that depend on 3 files

• BUT that is a lot to remember; hard to get right; easy to get wrong; etc

• We should automate that too.

16.1 Batch/Script files

• Batch files, AKA Script files can executed commands for us

• There are many different scripting engines

  • default on Windows - Batch files - .bat

  • default on Linux - Shell files - .sh

  • Powershell

  • "real" scripting languages

    • Python, Lua, Ruby, …​

16.2 Automation

• Automate the steps from part two using a Batch/Script file

  • it needs to do all the steps we’ve done automated

    1. making and going into build directory

    2. conan

    3. cmake

    4. clean up (leave the command line at the same path)

16.3 Test it

• Test your script by running it twice, back to back

• Test your script by deleting the build directory

• Test your script by deleting the build and the .conan directory (in your user space)

  • C:\Users\Computing\.conan\

• Test your script on another machine

Stretch Activities

Now you have SDL2 installed and working from your program, try to:

1. Make SDL log the "HelloWorld!" output, instead of using cout

   • What do you need to do differently?

2. Look up SDL’s documentation of Logging.

   • What control do you have over the logs?

   • Why might you want this control? - discuss with a collegue/friend

3. Ask SDL to create you a Window

   • Search SDL’s documentation for the function

   • What parameters does it need? What do they each do?