1.

Introduction
This document walks you through the installation steps required to get started with the Imperative
Programming course. Start by following the instructions for your operating system in section 2, then
continue to section 3. If you run into issues, make sure to check section 4 which outlines some common
issue and troubleshooting steps. Once completed, you should not need to install any additional software
throughout the course.

Disclaimer: version numbers mentioned in this document may become outdated over time. Availability of
versions may also differ based on your OS (version). For Windows this is mostly a non-issue due to our installer,
but on other operating systems you should typically use the latest stable version available to you. Do not go out
of your way to install older versions unless you run into issues.

2.a Windows Install (automatic)

Download the IPSetup-v1.5.exe file from Brightspace, and run the installer. This will install:
CMake 3.30.2
wxWidgets 3.2.5
MinGW 13.2.0
git 2.46.0
Follow the instructions in section 3

2.b Linux Install

Install git (e.g. sudo apt install git)
Install CMake (e.g. sudo apt install cmake)
Install g++ (e.g. sudo apt install g++)
Install wxWidgets (e.g. sudo apt install libwxgtk3.0-gtk3-dev)
You may need to install libwxgtk3.2-dev instead, which replaces the 3.0 package on newer
Ubuntu based systems
Follow the instructions in section 3

Tested on Ubuntu based systems, with CMake 3.22.1, g++ 11.4.0, and wxWidgets 3.0.5.

2.c macOS Install

Install Xcode Command Line Tools
Apple tends to switch up the method required for this, see these instructions or search for
ones specific to your OS version
Install Homebrew
Make sure git is installed by running git version in a terminal
If it's not installed for some reason you can install it using brew install git in a terminal,
or whatever other method you prefer

1 / 10
 Install CMake using brew install cmake in a terminal
Install wxWidgets using brew install wxwidgets in a terminal
Make sure that you have version 3.2.1 or newer if you have an ARM based device
Follow the instructions in section 3

Tested with a macOS Big Sur 11.2.3 VM, CMake 3.21.2, wxWidgets 3.2.1, and AppleClang 12.0.5 (versions
likely outdated by now).

Alternatively you can also try installing GCC/g++ using brew install gcc followed by brew link gcc
if you have issues with getting AppleClang to work.

Selecting the GCC 11.2.0 x86_64-apple-darwin20 kit in Visual Studio Code also worked for me
(again version likely outdated).

3. Editor installation
We assume that you will be using Visual Studio Code as your editor. It is possible to use your own editor/IDE
as long as it has CMake integration, or even build directly from the command line/terminal (see Appendix
A), but we do not officially support this. If you run into issues we are unlikely to provide support, and may
request you to try our Visual Studio Code setup anyway.

Perform the following steps to install and set up our development environment:

Install Visual Studio Code

If you prefer VSCodium this should also work, but not all of the extension might be available
Install Visual Studio Code extensions
Open the Extensions pane (Ctrl + Shift + X) on the left toolbar, or via View -> Extensions
Install the C/C++ Extension Pack by Microsoft
Make sure to select the extension pack and not just the C/C++ Extension
This adds several extensions that aid us with developing C/C++ code
Only CMake Tools by Microsoft is strictly required, the rest are optional
It provides UI integration to run CMake builds, thus unless you plan on manual
command line builds this is required
The default built-in build methods Visual Studio Code offers will not work as they
do not support CMake
Configure the Visual Studio Code extensions
Open the Settings page (Ctrl + Comma) via File -> Preferences -> Settings
Search for status bar visibility
Set Cmake > Options: Status Bar Visibility to visible

Now that everything is installed, we can open the wxCharles-demo test project (see Brightspace) and
attempt to build it using CMake. When the project is opened for the first time, we must configure CMake.

Open Visual Studio Code, then click on the File -> Open Folder... menu item, make sure to
use open folder and not open file
Select the folder directly containing CMakeLists.txt (wxCharles unless you renamed the folder)
and hit OK

2 / 10
 Press Ctrl + Shift + P to open the Command Palette (or go to View -> Command Palette...)
and execute the following actions
Execute CMake: Scan for Kits
This will detect the available compiler kits on your platform
Execute CMake: Select a Kit
This will select a compiler kit to use on your platform
On Linux this is typically GCC 11.4.0 or some newer version
On Windows this is typically GCC 13.2.0 x86_64-w64-mingw32
On macOS this is typically Clang 12.0.5 x86_64-apple-darwin20.3.0 or some
newer version
Note: versions may differ depending on your OS version
You may see multiple options if you have additional compilers installed. On Windows
especially make sure to select our installed GCC version as opposed to an older GCC,
MSVC or Visual Studio compiler. These are unlikely to work
Execute CMake: Configure
This will generate the build files for your platform and compiler kit

Now that CMake is configured, we can finally attempt to build the project. Click on the Build button (or
press F7) on the left side of the bottom statusbar/toolbar to start the build process (see screenshot below).
If all goes well this will finish without any errors.

To run or debug the application, click on the bug and play buttons to the right of the Build button (or
press Shift + F5 and Ctrl + F5 respectively). Normally the run option is sufficient. You should only need the
debug option if you plan on using debugging features such as breakpoints, or run into unexpected crashes.
Note that the use of such debugging features is optional, and not included in the course material. Clicking
on either option will rebuild the project if need be, so you do not need to first build yourself if you made
any changes to the code.

3 / 10
4. Troubleshooting
A good first step is to restart Visual Studio Code (and perhaps even your entire device). Changes to
the PATH environment variable for instance are not reflected until a program restarts.
After that a good sanity check is to open a terminal/command prompt/powershell and try to execute
git --version, cmake --version, and g++ --version (depending on what compiler you
have). These should return with expected versions. If they give you program not found like errors,
or the versions are wildly different than expected there is likely an issue with your installation of
these tools and/or your PATH environment variable.
Next make sure you have opened the correct folder as a folder. Look for the folder containing the
CMakeLists.txt file and open that folder. A common issue we see is that students have for
example C:\assignment\assignment\CMakeLists.txt and open C:\assignment as folder
instead of C:\assignment\assignment. This will cause the CMake Tools extension to not work
correctly.
Make sure that you select the right compiler. Especially on Windows if you select a Visual Studio or
older/different GCC one it will not work, as the wxWidgets install for Windows is tied to a specific
compiler version.
Since CMake will cache (i.e. store) settings/data in the background, you must delete this cache if you
have possibly cached incorrect settings. You can execute the CMake: Delete Cache and
Reconfigure Visual Studio Code action from the Command Palette to try and delete the incorrect
cache, and start the configuration process again.
Another issue with caching is that moving the folder after having ran the configuration likely causes
all kinds of errors. Again deleting the cache and doing a reconfigure may work. A more powerful
variant of this is to delete the entire build folder (which is where this cache is stored, it is in the
same folder as the CMakeLists.txt file), and to then restart Visual Studio Code.
Make sure that you try to build/run using the CMake Tools statusbar/toolbar on the bottom, rather
than a button Visual Studio Code may give near the top right if you have a code file open (or via other
built-in methods). Those methods do not use CMake and thus do not know how to properly build the
project with all required dependencies.
Finally you can also try to use the CMake: Clean Rebuild action from the Command Palette.
Normally CMake/your compiler will not try to recompile a file if it has not been changed. A clean
rebuild forces all files to be recompiled/built, whether the compiler thinks it is needed or not. This
may in some small cases also fix issues.

Windows specific
Windows Defender and third party Anti-Virus vendors may sometimes incorrectly mark our installer,
or even the program you compile from your own code as malware and remove/quarantine it. The
installer is typically white-listed after some time (it's an open source installer repackaging open
source software), but if this happens you can normally go into your anti virus settings and
allow/restore the executable falsely flagged. Windows Defender can be very finicky and you may
have to allow/restore multiple times before it finally takes effect. A more drastic option is to
(temporarily) disable real-time scanning entirely, but this is obviously not desirable for most users.
If you try to build/recompile your code while the produced executable program is still running in the
background, it will fail with typically some access denied type error on the executable program
file. You may not even notice the program is still running in the background as it may have

4 / 10
 crashed/hung in a weird way. If this happens open up your task manager (Ctrl + Shift + Escape) and
look if there are processes still running (usually named wwcharles.exe or main.exe), and kill
them. This is a Windows limitation as it locks the .exe file while a program is running, which is not an
issue on Linux/Mac. As long as your programs exit cleanly it's not something you have to deal with,
but if you write code that runs for a very long time, or even has infinite loops, you may run into this.
We have observed issues with OneDrive in the past, such as some key files being automatically
deleted by Windows or other vague issues causing things to not work. We therefore recommend not
placing your code under a OneDrive folder. Windows tends to throw stuff in OneDrive folders even
when you do not expect it, such as desktop files being under C:\Users\
<username>\OneDrive\Desktop rather than C:\Users\<username>\Desktop. Pay special
attention to this.
Windows has a maximum path length limit of 260 characters. While you can disable this limit to allow
longer paths, not all programs work well with this as developers need to take steps to opt-in to this
new behavior. Try to avoid placing your code in deeply nested folders with very long folder names
such as C:\Users\<long username>\Documents\University\Semester 1\Imperative
Programming\Assignments\Imperative Programming Assignment 1\code\.... You can
always archive your code later with these long names, but while developing keep it sensible and stay
well within the 260 character limit as CMake will also generate a whole bunch of files and folders in
the background relative to your code folder.
Spaces in paths can in rare cases be problematic. While we have never been able to reproduce this in
testing, we have observed some students have error messages such as C:\Program can not be
found when trying to execute a program such as C:\Program Files\example.exe. In such cases
consider changing the installer location to be into a path that does not contain any spaces, and then
also use a path to store your code without spaces, for example C:\Projects over C:\Users\John
Doe\My Documents.
Some tools may not properly handle non-ASCII characters in paths. If you observe issues with weirdly
corrupted path names it could be that you are using a path such as C:\Users\
<username>\Documents\... where <username> contains non-ASCII characters. In such cases we
recommend placing your files in a different path, for example C:\Projects.

Appendix A: Command line building

It is also possible to build directly from the command line, rather than using Visual Studio Code. This may be
preferable if you're used to working with editors such as vim. Make sure to install the dependencies for
your platform as listed in the sections below. If you're not familiar with command line building, you should
probably stick to Visual Studio Code. This method is provided as an alternative, but not officially
recommended.

Open a terminal in the directory containing the CMakeLists.txt file

Run cmake -S . -B build
This will configure and generate the build files using the current directory as the source
location, and places all generated files in a newly created build directory
You should only have to run this once, unless you add/remove/rename any source files
Run cmake --build build
This will compile and build the application
You should run this every time you change agent.cpp

5 / 10
 If successful, you can now run the application using ./build/wxCharles
See man cmake for further useful options, such as --clean-first or --target clean

Appendix B: Windows Install (manual)

You should not need to install these dependencies manually, prefer to use the installer (see 2.a). These
instructions serve as a fallback in case the installer fails for whatever reason.

Install CMake
Tested with latest x64 stable release 3.24.1
During installation, make sure to enable Add to PATH option (see image below)
Install Mingw-w64
Download and extract the x86_64-12.2.0-release-posix-seh-msvcrt-rt_v10-rev2 7-Zip archive
You could try the installer (untested)
During installation, make sure to select the following options
Version 12.2.0
Architecture x86_64 (64-bit)
Thread model posix
Build revision 2
C runtime msvcrt
Exception seh
Add MinGW-w64 bin folder to PATH environment variable (see images below)
e.g. C:\Program Files\mingw-w64\x86_64-12.2.0-posix-seh-msvcrt-
rt_v10-rev2\mingw64\bin
Install wxWidgets manually
Download latest release (3.2.1) Header Files for MinGW-w64 12.2.0
Download latest release (3.2.1) x86_64 Development Files for MinGW-w64 12.2.0
Create folder for wxWidgets, e.g. C:\wxWidgets-3.2.1
Extract headers to wxWidgets folder, i.e. C:\wxWidgets-3.2.1\include
Extract development files to wxWidgets folder, i.e. C:\wxWidgets-3.2.1\lib
Rename C:\wxWidgets-3.2.1\lib\gcc1220_x64_dll to C:\wxWidgets-
3.2.1\lib\gcc_dll
This is needed for the FindwxWidgets.cmake module to detect the MinGW version
correctly.
Add libraries to PATH environment variable, i.e. C:\wxWidgets-3.2.1\lib\gcc_dll (see
images below)
Set wxWidgets_ROOT_DIR environment variable to wxWidgets folder, i.e. C:\wxWidgets-
3.2.1 (see images below)
Install git
Using the 64-bit Standalone Installer with default options should suffice
Make sure git is added to the PATH environment variable

CMake install options:

6 / 10
wxWidgets folder structure:

Type the following in the start menu to open the Edit environment variables for your account
dialog:

7 / 10
Next select Path under the top user variables section, and click Edit...:

8 / 10
Use the New and Browse... buttons to add the correct paths for wxWidgets and MinGW as shown below,
and then click OK:

9 / 10
Now click New... in the top user variables section and add the following variable, and then click OK on
both the New User Variable dialog and Environment Variables dialog:

10 / 10