The Cross-platform Startup SPA Solution with CMake offers a starting point for your project development and testing.
In CS3203 we offer two alternatives for your project development:
Please note that there is no difference in grading when choosing one of the two alternatives, as long as your README states clearly if we are to use a Windows machine or a MacOS/Linux machine for your final testing. The compilation and running process should be flawless no matter which alternative you choose.
This documentation is applicable to cross-platform development using CMake!
The files provided contain the AutoTester libraries needed and used for final testing in CS3203. Please make sure that you read the documentation about the AutoTester to be able to integrate your code with the AutoTester.
Download spa-cp.zip and unzip it to your local directory.
Before adopting this Cross-platform Startup SPA Solution, please note that:
All members in the team have to use CMake (even if they develop on Windows, MacOS, or Linux)! Do not mix using Windows Startup SPA Solution with using CMake in the same team!
Some basic knowledge of CMake is required. When working with CMake, you mainly control the building process via editing CMakeLists.txt file as opposed to using the IDE’s GUI to add new files and add dependencies.
In CMake, we use a unit testing framework called Catch2. This is because CPPunit for unit testing in Visual Studio is not available in MacOS or Linux.
Team members who are using Windows may still use Visual Studio. However, those who are on MacOS or Linux need to choose a different IDE since Visual Studio for Mac/Linux does not support C++ by default.
Warning: We recommend that the entire team uses the same platform and coding environment if possible. While it is possible to develop cross-platform code which works the same on both platform, there are significant differences between the clang/gcc compiler toolchain and MSVC toolchain. If the whole team is not developing on the same platform, you might end up spending large amount of time ensuring your code works the same on both platform.
If you are developing in Windows, we recommend using Visual Studio Community 2022/2019.
Do refer to Section 1.1 in the Documentation for Windows Startup SPA Solution on how to install Visual Studio 2022/2019.
CMake is also installed during the installation of Visual Studio 2022/2019.
If you are developing in MacOS, we recommend using CLion.
On macOS, CLion will require Xcode. Please proceed with the installation.
You will also need to install CMake and configure CLion for using CMake.
Our solution is organized by into separate project folders and each contains its own CMakeLists.txt file. The root CMakeLists.txt control which one to build by using add_subdirectory() commands. Additional CMake scripts and utility functions are to be placed under cmake folder.
Cross-platform Startup SPA Solution contains five folders (under src):
spa: This folder contains the implementation for your SPA. When compiled, this folder produces a library that is used by all other projects.
It is possible for dependent libraries' headers to be accessible to those projects that use them. Although there are many ways of achieving this such as include_directories($SOMEPATH) at root CMakeLists.txt, CMake provide a clean way to achieve this via target_include_directories() function. Please refer to src/spa/CMakeLists.txt.
autotester: This folder contains routines to call the methods you have implemented under SPA.
This library is found via CMake script under cmake/FindAutotester.cmake. After find_package(Autotester) is successful, CMake variable ${AUTOTESTER_LIBRARIES} will be populated which you can then use in target_link_libraries() call to link against.
unit_testing: This folder will contain unit tests created for your SPA.
We are using unit testing framework Catch2. This is a header only library which provide macros for writing unit tests. After linking against the library (included under lib folder), unit_testing (and integration_testing) produces executables which run the unit tests. Since normally, an executable will require a main method to build successfully, we have added an empty main.cpp with definition #define CATCH_CONFIG_MAIN. This tells Catch2 to generate a main method in that file. Please ensure there's only one file with that definition.
If you are using CLion, it has built in support for Catch2. To run the tests specified in the project:
Run > Edit Configurations > click the + sign at the top left corner and select catch test.integration_testing: This folder will contain integration tests created for your SPA (using same unit testing framework as unit_testing).
There are two ways to work with CMake in Visual Studio.
Recommended: Use Open Folder mode without using .sln solution files.
File > Open > Folder > (navigate to the folder with CMakeLists.txt)
Visual Studio automatically generates the CMake cache and detects targets specified in CMakeLists.txt.
Internally, Visual Studio uses ninja build system(which is configurable via CMakeSettings.json) to build the final binaries. You can control this process(such as where CMake cache folder is) via CMakeSettings.json and .vs folder. Project specific settings such as arguments to pass during debugging is stored in .vs/launch.vs.json. Our CMakeSettings.json configures a 32 bit build and the location of built binaries.
Not Recommended: Use .sln mode where you generate Visual Studio .sln file from CMake and open the .sln file normally. When you are making changes such as adding files or reorganizing code folder structure, you should edit the CMakeLists.txt and regenerate the .sln files, instead of relying on the Visual Studio.
Once the folder is open, debugging works the same as Visual Studio .sln files. Just putting a breakpoint on the line you want to break and in debug mode it will pause at that line accordingly. No special configuration is required.
To open a project:
File > Open > Folder > (navigate to the folder with CMakeLists.txt)
CLion will then proceed to generate CMake cache after which you can build the project.(Ctrl+F9).
If you don't use CLion and you mainly work in terminal, you can follow the instructions below to build the project.
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"$ brew install cmake llvm$ mkdir build$ cd build$ cmake ..$ make -j4$ cd ../tests/test, to check if you have everything setup correctly: $ ../build/src/autotester/autotester Sample_source.txt Sample_queries.txt out.xmlIf you are an open source fanatic and manage to convince your whole team to switch to Fedora, the instructions are pretty simple for Fedora using GCC:
# dnf install cmake make gcc-c++$ mkdir build$ cd build$ cmake ..$ make -j4$ cd ../tests/test, to check if you have everything setup correctly: $ ../build/src/autotester/autotester Sample_source.txt Sample_queries.txt out.xmlWhen I follow the instructions, I get this error: Beginning to parse Simple Program. End of parsing Simple Program. terminate called after throwing an instance of 'std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >' Aborted (core dumped). What should I do?
My program runs, but the output does not look correct (i.e. files are not parsed correctly)
I want to use Ubuntu, but I get errors.
CXX=clang++ CC=clang cmake .. instead of just cmake ..