01: Gearing Up

This is a first draft of basic installation instructions for each operating system. I have to actually test the instructions for Linux and OSX so if you're on those then assume the instructions are rough. The Windows instructions though are fairly well tested on Windows Home as of Jun 2024.

The goal of these instructions is to configure a very basic developer environment that is the same on all platforms. This means that it's not really the most optimal environment on each platform. For example, on OSX I would just use XCode to make an iOS app, not this setup. On Windows I would use Visual C++ to do most of my work if I was making a Windows only desktop application. Linux would probably be nearly the same as this configuration.

If that's the case then why use this environment? Because it's able to create the exact same game on all three platforms with the same source code in the same way. This helps both me and you in the long run:

1. I don't have to write 3-4 different versions of every piece of code and all of the instructions for every platform. Since this course is intended to help as many people as possible I have to reduce the amount of variation between everyone so that I can help you all. If I have to accommodate every company's product then I'll be overloaded with a far too high support burden.
2. This developer environment is simple. There's no crazy UIs, plugins, insane libraries, tools, or anything too complicated. It's just a C++ compiler, a text editor, and a build tool to get started.
3. Because this configuration works pretty much anywhere you can make your games for any platform. This lets more people learn C++ but also lets you give your games to more people, which is always more fun.
4. Starting out with a simple setup like this makes it easy to move on to more complicated tools like XCode and Visual C++. Those tools usually assume you know something about C++ compilers that they also try to hide from you. If you are familiar with building your own games manually, then you'll have no problem fixing build issues in other tools.

That being said, if you're already familiar with another development environment, editor, or compiler then feel free to use it. You should be able to take my instructions and translate them to your favorite tools easily.

Windows

Windows is probably the most challenging system to configure for this course. To simplify things I've created a setup script that will install everything you need, but before you run this script you should know what it installs:

1. git
2. winget
3. chocolatey
4. Windows Terminal
5. WizFile
6. CMake
7. Geany and Geany Plugins
8. winlibs
9. conan
10. Meson

If you prefer to install your software manually then this is the list of things installed by the automation script. If you already have some of these things then the script should skip them or upgrade them.

Start a PowerShell window NOT AS ADMINISTRATOR. I repeat, you do NOT have to be Administrator to run this script. It will become Administrator as it needs. Then run these two commands:

irm https://learncodethehardway.com/setup/base.ps1 -outfile base.ps1
powershell -executionpolicy bypass .\base.ps1

DO NOT LEAVE YOUR COMPUTER. This script will install software and prompt you for the password to an Administrator account. Stupidly, a lot of Windows installers have "timeouts" and will exit if you don't enter a password fast enough. Watch it run, answer any password prompts that come up, and if all goes well you'll have the base setup.

Now, do as the script commands a CLOSE YOUR POWERSHELL. Next, you'll start a new PowerShell and repeat the process with these two commands:

irm https://learncodethehardway.com/setup/cpp.ps1 -outfile cpp.ps1
powershell -executionpolicy bypass .\cpp.ps1

Again, DO NOT LEAVE YOUR COMPUTER and answer all the logins and prompts to accept installs. Once this script runs you'll have everything you need. Keep these scripts around since you can re-run them to update your software.

You should now test your installation:

1. Start Terminal (aka Windows Terminal) to get access to a terminal. You can access this by hitting the Windows Start keyn (winkey) and typing "Terminal."
2. Type the command git and confirm it runs without error. If you get The term 'git' is not recognized then your install didn't work.
3. Type the command c++ and confirm it also runs. This time it will have an error of c++.exe: fatal error: no input files which is normal. If you get The term c++ is not recognized then your setup didn't work.
4. Type the command meson and confirm it also runs, and just like C++ gives you an error but not term not reconized.
5. Finally, make sure you can run Geany and WizFile. WizFile is entirely optional but it is so useful that I'm just having everyone install it. It basically gives you lightning fast file searching, which will help tremendously while you work.

If all of that works then jump to the end of this lesson to do the final test of your configuration.

Exploring the Other Installer Scripts

There's also an additional script named extras.ps1 that you can run to get a few additional little tools. If you want to learn more about these scripts you can visit the git repository where the project is stored. I also have installers for many other languages, like Python, Go, and Rust.

OSX

For OSX you should only need to install XCode from the AppStore and have almost everything you need. Once you have that you'll want to install a text editor, and a few other project. Here's the full list of what you need to install:

1. XCode
2. Geany is a really good simple text editor that has all the features you need, but not so many that you'll get confused.
3. From the same site also install the Geany Plugins. They'll help you later for some things.
4. Meson which will be our primary build tool.
5. CMake

You should then confirm your installation by doing this:

1. Open Terminal from your Applications folder and pin it to your Dock.
2. In Terminal type the command: git and confirm that it runs. If you see command not found then you didn't install XCode correctly.
3. Next type c++ and make sure you see clang: error: no input files which confirms you have a compiler.
4. Next type meson and confirm that works as well.

If all of that works then jump to the end of this lesson to do the final test of your configuration.

Linux

The rough instructions for Linux are:

1. Install a C/C++ compiler, either Clang or GCC.
2. Install Geany and Geany Plugins unless you have a test editor you like.
3. python 3.12.4 or close to it
4. Meson
5. git
6. CMake
7. The build-essentials for your version of Linux. This is usually some "meta package" that installs a ton of libraries, include files, compiler tools, and other things you need to compile code in your version of Linux.
8. Install whatever libraries you need to make graphics work on your Linux. You might need OpenGL support, fonts, etc. The builds in this course try to install everything you need but you may need to do a bit of work to add more libraries.

Here are specific instructions for Ubuntu 24:

apt install build-essential \
  git geany meson cmake \
  freeglut3-dev libsndfile-dev \
  libxcursor-dev libxrandr-dev \
  libudev-dev

To test your setup, do this:

1. Open your Terminal of choice.
2. Type git and make sure it runs.
3. Type c++ and make sure it runs too. Remember, you'll get an error clang: error: no input files in Clang and fatal error: no input files with GCC.
4. Next type meson and confirm that works as well.

If all of that works then jump to the end of this lesson to do the final test of your configuration.

A Quick Terminal Crash Course

To continue with this course you'll need to learn a little bit about how to use Terminal. This is also called "using the Command Line." because you have an input line where you enter commands. If you already know how to use the command line and Terminal then skip to The Big Test section at the end.

Why Use the Command Line?

While the Terminal and CLI is quicker it requires you to remember the commands and how to use them. It also requires you to know the locations of your files. With your mouse and folder windows you can visually see what you have to do, so it takes less knowledge and memory. That's the main reason why all computers do not use the CLI anymore.

The question is, why learn to use the Terminal and CLI if it's harder? Because it has massive powerful benefits both for your productivity and for your education as a future programmer:

1. The CLI is the same as programming in C++ or any other programming language but simpler. In C++ you are using language to control the computer. In the CLI you are also using language to control the computer but with a far simpler language.
2. Doing large scale repetitive things with the CLI is far easier. If you had to move 10000 files from one directory to another with "text" in their name you'd probably spend a good hour or more just clicking your mouse. With the CLI you would use one command mv *text*.* NewDirectory and be done.
3. CLI operations are repeatable and scriptable. If every day you were required to collect a bunch of files in a certain way, run a program to convert them, and then send them to a server, it would be annoying with the mouse. With the CLI you could write a nice little file of all your commands that did this work for you, then simply run that one file each day.
4. A lot of programming tools are CLI tools. You can do quite a lot of programming with modern IDEs but at some point you'll be forced to use command line to use some tool, deploy your code to a server, run the really good validator tools, and generally interact with other programming communities.
5. The CLI is freedom of choice. When you use the CLI you can easily use any new programming language, or write your own tools to help with your work. Without the CLI you have to wait for someone else to update your IDE to support new programming languages and you'll have to write your own GUIs for your simple tools.

That should be enough reasons to use the command line but to use it effectively you'll need to learn some more concepts.

How Commands Work

Your Terminal is usually called a "Command Line Interface" or CLI for short. The name is very literal since you are typing commands, on a line in your Terminal, to interface with your computer. The CLI is a text based alternative to clicking your mouse on buttons and files in your file browser (Finder on OSX, Explorer on Windows). For example, if you want to move a file from your Documents to your Desktop folder with a mouse, you would do this:

1. Find the Documents folder icon and double-click it.
2. Move that window to the side so you can see your Desktop.
3. Click and hold your mouse button, then "drag" the file out of Documents onto your Desktop.
4. Release the file and done. You moved it. If you want to do more complex operations, you right-click-hold so you have options when you drop.

This same action is done with one command:

mv ~/Document/myfile.pdf ~/Desktop/

How Commands are Formatted

Every command command has the same format:

1. It starts with a single word, no spaces, and capitalization matters. In this case mv.
2. You then have a series of "arguments" separated by spaces. In this case ~/Document/myfile.pdf and ~/Desktop/.
3. You can also have a set of options, which typically have either one - or two - to start them. An example would be -recursive on Windows or -r on OSX.
4. Some options can also take an additional parameter, so for example -exclude *.txt.

Putting that all together you'll have the format that's something like this on OSX:

command [-o] [--option] [--option value] arg1 arg2 argN

When you see the [] around something it means that it is "optional" and you don't actually type those. On Windows it's almost the same:

command [-o] [-option] [-option value] arg1 arg2 argN

Another notation you should know is a parameter that's shown as <arg> which usually means it's required. If you see me write that then you'll get an error if you don't include it.

The Common Commands

To start off I'm going to teach you the most common commands you'll use. Each of these commands use the format I just described, so all you need to do is learn what they do and then start using them.

pwd

Print Working Directory just tells you the directory you're currently in. Most shells tell this all the time with text before the prompt, but sometimes you need to use this in scripts or are dumb like me and don't even see the text before the prompt so you keep typing this command because you're old.

ls [path]

Lists the contents of either the current directory (without path) or the given path. Example: ls ~/Documents to list your documents.

cd [path]

Change to a new directory (thus change directory). Takes one optional path like ls. Example: cd ~ to go to your home directory.

cat <path>

Concatenates files together, but really people use it to dump the contents of files to the Terminal. Example: cat myshoppinglist.txt

touch <path>

It's intended to change the file's date/time stamps, but people really use it to make empty files. Example: touch newfile.txt

mv <frompath> <topath>

Moves a file from the <frompath> location to the <topath> location. It's a good practice to use ls or start/open to confirm that the <topath> exists before you do this. The mv command is really renaming a file, not just moving it, so you can use it to just change a file's name even if you don't change its location. Example: mv myshopplinglist.txt ~/Documents/shoppinglist.txt

cp <frompath> <topath>

Copies a file from the <frompath> location to the <topath> location. This is different from mv because there will be a file in both locations with the same contents. However, mv removes the file in the original location, and places it in the new location. Example: cp myshopplinglist.txt ~/Documents/shoppinglist.txt

rm <path>

Removes a file from your computer. THIS IS PERMANENT. There are many options to rm so see the next section for finding the instructions. Example: rm ihatethisfile.txt

start <path> on Windows and open <path> on OSX

We'll cover this in great depth later because they're very useful, but these commands basically simulate double-clicking on the file to open it.

c++ <sourcefile.cpp> -o <output>

You'll use this command to compile single .cpp C++ source files into a program you can run <output>. Example: c++ ex01.cpp -o ex01

I recommend you create a document or little card with these commands and instructions so you can refer to them while you work. This is called a "cheat sheet" and you may even be able to find a cheat sheet online for your Terminal.

Getting Help

These descriptions of the common commands are incomplete on purpose because I want you to find the documentation for them. Here's how you do that:

1. On OSX and Linux you can type man [command] to get a help document for that command. For example, man cp gives you the full documentation for the cp command.
2. On OSX and Linux you can also search online for [command] man page to find a man page for something you may not have installed or can't find. The addition of "linux man page" is a cheat code to make Google show you the actual man page rather than trash tech support hack sites. If this eventually gets taken over as well then try [command] site:man7.org or [command] site:die.net. While these will be Linux documents they will be pretty close to the OSX version.
3. On Windows the best resource is Microsoft's own documentation at learn.microsoft.com.
4. A good search for PowerShell commands is [command] powershell site:learn.microsoft.com. This will focus the search on their site and give you the correct documentation.
5. One BIG warning about Microsoft's PowerShell is the commands you type are usually short aliases for a larger name. For example cp is an alias for Copy-Item. Don't be confused if you search for cp and see a page for Copy-Item.

What's a Path

A path is simply a way to identify the location of a file on your computer. You can think of the path as "going through" a series of directories (folder) to get to your file. Each folder (directory) is separated by a / (and on Windows \ or / works). To understand this you'll need to know a few terms:

root

This is the "top" of your computer, or the place where all your directories "grow" from. Get it? Like growing from the root of a tree. On OSX this is usually indicated with / and on Windows it's the letter of your main drive, usually C:\.

segment

A path segment is each part of a path separated by a / (or \ on Windows).

home directory

This is where your files typically start living. On OSX this will usually be /Users/<youruser> starting from the root. On Windows this is C:\Users\<youruser>. On my computers this is /Users/lcthw and C:\Users\lcthw.

home alias

Windows PowerShell and OSX's zsh (or bash) have an alias for your home with the ~ (tilde) character. You can put that at the start of your path to begin the path from there. So, to get to your documents you can do ~/Documents (remember / does work on Windows but it'll translate it to \).

current dir alias

Most shells also use . to mean "the current directory" so you can use it in paths like with ~. It's usually used to ensure that you run a command in your current directory or force a command to work on the current directory. For example, to run a program I just compiled I could do ./ex01.

Now that you know some terms we can talk about how a path works:

1. A path will be a sequence of segments separated by / (or \ on Windows).
2. A segment will either be a directory or a file, but the file can only be at the end of the path. That's because each segment is going into each segment to reach the final location.
3. The path can either start at the root /, the ~ home alias, or . the current working directory. The default is the . current working directory, but some commands don't honor this and it's best to be explicit about where it starts.
4. Finally, if any part of a path is invalid then the whole path is invalid. You can use TAB to complete most path segments and files, so read the next section to learn about that.

Now that you know how a path works, let's look at a few examples.

/Users/lcthw/Documents/learn-cpp-the-hard-way.pdf

This starts at the root /, then goes into the Users directory, then my home lcthw directory, then my Documents and finally reaches my learn-cpp-the-hard-way.pdf file.

~/Movies/ex01.mp4

This starts at my ~ home alias, then goes to my Movies directory, and finally reaches the ex01.mp4 file.

./builddir/ex01

This starts at the . current directory alias, goes into builddir, and finally runs the ex01 program.

Keep in mind when I say "goes into" you're not literally moving into those directories. It's more that the shell uses this path to find your file on the computer, but your shell stays where it is when you run the command. The exception to this is with the cd command which is supposed to move you to a new place.

TAB Completion

The advantage of using the mouse is you don't have to remember any commands or where a file is. You can visually see the icon, grab it and move. The mv command does help you though since you can hit tab to complete paths or commands. If you type this:

mv ~/Des

Then hit TAB (maybe twice) in your shell will complete the possible files that might finish the word. In this case, if you hit TAB there it should just type out Desktop for you.

Using start/open

One problem you'll run into is your brain has been trained on your computer's Graphical User Interface (GUI) and you probably can't map that version of your computer to the Terminal's version that uses paths. The best way to start mapping the two is to use the start command on Windows and the open command on OSX. These commands (start/open) allow you to "double-click" on things from your Terminal. This will open them in a graphical window just like if you double clicked the file.

Let's say you are in Terminal and have no idea where you are. From the Paths section of this tutorial you know that . means "where I am now" or "this directory right here." If you then type start . on Windows or open . on OSX you'll immediately open a window of your current directory so you can see where you are just like you would normally with your mouse.

You an use the start/open command in many different ways when you are stuck. In these examples I'll use start but if you're on OSX just assume I mean open. They work pretty much the same on both platforms.

1. If you need to see where you are use start .
2. If you want to open a file in its application then start thefile.doc will open it just like if you double-clicked on thefile.doc.
3. If you want to see what's in a directory from where you are use start MyCoolFiles.
4. If you want to quickly open your home directory use start ~.

From Mouse to Terminal

The reverse of start/open also works by dragging any file you see in a window into your Terminal. Let's say you're looking at folder that has a file you want to use in your Terminal. Just click-hold to grab the file, and drag it right into your Terminal window. When you do this the file's entire path will be pasted into your terminal so you can work with it. Let's say for example it's a file named test.pdf in the Documents folder and you want to copy it to where you are in the Terminal:

1. First, start typing the command with cp (there's a space after cp here).
2. Then open the Documents folder and click-hold the test.pdf file to drag it.
3. Drop test.pdf onto your Terminal window and it should now paste the full path there, making your command look something like cp C:\Users\lcthw\Documents\test.pdf. On OSX it'll probably be similar to cp /Users/lcthw/Documents/test.pdf.
4. Next hit space bar and complete the command with . to copy the file here. On Windows it should now be cp C:\Users\lcthw\Documents\test.pdf . and on OSX it looks like cp C:\Users\lcthw\Documents\test.pdf ..
5. Finally, just hit ENTER and the command will run copying the file. You can confirm it's there with the ls command.

The Big Test

You are now going to attempt to build the game-dev-starter-pack project to confirm that your computer is fully setup and ready to go. If you can't build this then check your setup again, try the install one more time, and if all else fails, contact me so I can find out what's different about your computer.

For Linux and OSX people, you'll open your Terminal and get these commands to work:

git clone https://git.learnjsthehardway.com/learn-code-the-hard-way/game-dev-starter-pack.git
cd game-dev-starter-pack
./scripts/setup.sh
meson compile -C builddir
./builddir/sfmldemo

For Windows your commands are almost exactly the same except for one:

git clone https://git.learnjsthehardway.com/learn-code-the-hard-way/game-dev-starter-pack.git
cd game-dev-starter-pack
powershell -executionpolicy bypass .\scripts\setup.ps1
meson compile -C builddir
.\builddir\sfmldemo

I highly recommend you do not copy-paste this entire sequence. Instead, copy each command and confirm it works. If this all works and you get a little bouncing smiley face game then you're done. Click the left mouse to hit the smiley from the left, and right mouse to hit from the right.