Skip to content

Latest commit

 

History

History
519 lines (412 loc) · 21.8 KB

README.md

File metadata and controls

519 lines (412 loc) · 21.8 KB

README

CMake Multi Platform Build docker gtest valgrind cppcheck

This repository contains material and source code examples corresponding to the "Algorithm & Datastructures" lecture at FOM Hochschule für Oekonomie & Management gGmbH.

The source code can be compiled "traditionally" utilizing CMake or conveniently compiled and executed in a Docker container.

Any reasonably recent Debian version or Debian-based system like Ubuntu or Linux Mint will be suitable for this guide, either running directly on the computer or within the "Windows Subsystem for Linux".

Table of Contents

Quick Start: Local Build on Commandline

The following steps describe the minimal environment to download, compile and run the examples from this repository - and how to create own build targets. No IDE is required yet, it all works on the commandline.

Clone Repository

This section describes, how to "clone" all the files in this reporitoy to have them available locally.

  • First, we need git for it - so let's install it:
# sudo or do as user `root`
apt-get install git
  • Then as "normal" user (not root!) clone this repository locally. Note: This is cloning via https Web URL. Alternatively, ssh could be used.
# cd to your local workspace folder of choice
git clone https://github.com/thorstendikmann/fomss2024aud.git

Local Build Requirements

This section describes how to compile and run the source code directly on the computer.

  • Most notably, a C/C++ compiler suite needs to be installed. Luckily, Debian covers most of if in the package build-essential. We additionally need cmake and the gdb Debugger.
# sudo or do as user `root`
apt-get install cmake build-essential gdb

Local Build Execution

This describes how to compile the source code files in this repository and execute examples.

  • We're running an out-of-source build in the build folder (= the created binaries and auxiliary files will be in a separate directory).
mkdir -p build && cd build
cmake ..
  • Let's run an example
make
bin/hello/hello_world_c

Add own source code (from scratch)

  • It's recommended to utilize the src/user folder for own developments. To avoid potential conflicts with the repository, let's create a separate folder for you. Assuming xy are your initials:
# cd .. # if you`re still within the build dir!
mkdir -p src/user/xy
cd src/user/xy
  • Let's create a new source code file - and a cmake file called CMakeLists.txt.
touch helloxy.c
touch CMakeLists.txt
  • Open these files in your editor of choice and add the following content:
// helloxy.c
#include<stdio.h>

int main(void) {
	printf("Hello World from XY\n");
	return 0;
}
# CMakeLists.txt
add_executable(helloxy helloxy.c)
  • Now we can compile and execute this. Let's go to the build folder first:
cd ../../../build
cmake
make

bin/user/helloxy

Work on exercises (from "snippets")

  • Best is to copy the relevant folder from src/snippets to your src/user/xy folder just created above, e.g. for factorial example in []
cp -r  src/snippets/01_einfuehrung/factorial src/user/xy/
  • Now modify the CMakeLists.txt in the copied folder to adjust the name of your build target:
add_executable(factorial_xy factorial.c)  ## replace the _snp by _xy (or whatever)

Integrated Development Environment

A graphical IDE is optional, but generally considered to be very useful supporting the productivity in the development process. Generally, any IDE will do the job. Visual Studio Code though is recommended due to being free, available for all common operating systems and quite lightweight. It supports the "common" (and also recommended setup) of utilizing Windows Subsystem for Linux very well. Installation and setup is documented following these links:

Running CMake in Visual Studio Code

  • Open the fomss2024aud folder by File -> Open Folder from the menu.

  • Note: If using WSL, open the folder from your WSL drive. It is available via Explorer within the Linux drive - or directly by typing in \\wsl.localhost\Debian\home\<USER> (use "Ubuntu" instead of Debian, depending on your installation and replace <USER> by your WSL Linux username).

  • Note: Once a WSL folder is opened, VS Code will install an extension into your WSL instance. In the bottom left, a blue icon will indicate

    Any extension needs to be installed within this "remote" environment on WSL.

  • Install extension CMake Tools.

  • You can run CMake directly from VS Code. A comprehensive tutorial can be found here - in short:

    • Press Ctrl+Shift+P, type "CMake: Configure" and choose the entry.

    • Now CMake should have generated the build files in the build/ folder, as if you have called it from the commandline. We then run a build (equal to cmake .. --build or make on the commandline from the build folder):

  • Note: When you create new build targets in a CMakeLists.txt: To select your new target in Visual Studio Code, you may have to repeat this process!

Running Programs in VS Code

  • It is recommended, to create a CMake Build Target first. See section add own source code. In other words: There must be a add_executable(...) in one CMakeList.txt for every of your application containing a main() function.

  • With installed CMake Tools extension, every CMake Build Target is available within the CMake menu (see yellow highlight). The current target can be changed by clicking the pencil icon (green highlight). The code can be executed via the arrow button (blue highlight) - either in debug or just launch mode without debugging.

  • Details can be found in the docs: CMake: Debug and launch

Interacting with the repository

This repository will be frequently updated. The following is a "cheat sheet" of commands to ensure the local repository can get these updates - and some "first aid" commands to troubleshoot. This is just a brief overview of few basics - a more sophisticated intro into git can be found at git-scm.com

Cleaning the build folder

  • The benefit of an "out-of-source"-build is to be able to clean up the whole repository by just deleting contents in one single folder. The "soft" way of cleanup leaves all CMake files in place and just cleares the build target.
make clean
make       # Re-compiles everything
  • Sometimes, just deleting everything in the folder and "starting fresh" is worth a try. Just make sure you're in the right folder, before recusively deleting everything ...
cd build
rm * -Rf   # DANGEROUS! Doublecheck before executing!!

cmake ..   # Re-initialize and ....
make       # ... build everything

Getting updates

  • Usually, a pull will do. From the git docs: Incorporates changes from a remote repository into the current branch. If the current branch is behind the remote, then by default it will fast-forward the current branch to match the remote.
git pull

Reverting local changes

  • When reverting local changes in a particular <file>, often it's best to do:
git checkout -- <file>
  • When the repository should be brought back to it's remote state, this command is the last resort. Careful: This will simply discard all local changes and DELETE all untracked files, including them in your /src/user folder!
git reset --hard  # DANGEROUS!

Optional parts

These parts go beyond an initial minimal setup to be able to compile and execute the given examples. Within the lecture, additional libraries are utilized which are not necessary from the very beginning. Their installation is described below.

Today, Docker is common to have an "all in one" build environment, especially to ensure compatibility and perform integration checks based on defined environments. The scripts of this repository can be executed in a docker environment. Setting up Docker is therefore as relevant as it is instructive.

Beyond the lecture, the scripts contained in this repository can be used to experiment with other programming languages and (build) environments. Optional, but a good start for a playground.

Recommended addons

Boost

  • Boost is a library collection offering many additions to the C++ standard library, including structures and algorithms.
  • Install boost libraries (... all)
apt-get install libboost-all-dev
  • Ensure you run CMake with the -DWITH_BOOST=ON option, e.g.
cmake .. -DWITH_BOOST=ON

GoogleTest

GoogleTest is a well-known testing and mocking framework for C++. It's for unit testing "and beyond", while we will docus on utilizing it ensuring our algorithms do what they're supposed to.

apt-get install googletest libgtest-dev
  • Ensure you run CMake with the -DWITH_GTEST=ON option, e.g.
cmake .. -DWITH_GTEST=ON

Doxygen

Doxygen is a documentation generator. Especially in larger projects it's often helpful to have a central website-based code documentation. With additional tools (from graphviz) relationships and dependencies within the source code repository can be visualized.

apt-get install doxygen graphviz
  • Ensure you run CMake with the -DWITH_DOC=ON option, e.g.
cmake .. -DWITH_DOC=ON

Valgrind

For checking proper memory management, valgrind is the tool of choise.

  • Installing valgrind
apt-get install valgrind
  • Running valgrind by simply inserting it "in front" of command to be executed.
valgrind bin/hello/hello_world_c

cppcheck

Additional static code analysis tool to detect potential issues with the source code.

apt-get install cppcheck
  • In the main folder run
cppcheck src --force
# A good set of warnings for this lecture:
cppcheck src --force  --enable=all --suppress=unusedFunction --suppress=redundantAssignment --suppress=variableScope --suppress=missingInclude --inline-suppr --template=gcc

Docker-based Build Environment

Installing Docker

Based on the given operating system environment, there are different ways how to install Docker:

apt-get install docker

Building and Executing

  • The Makefile contains several commands to simplify the build and execution with docker.
make dockerbuild  # only build image
make docker       # build & run
  • Running the image will execute run.sh inside the image - The script just calls a couple of compiled programs.
  • The Dockerfile also contains a section to automatically start a "documentation server" - this will be available at localhost:8080/ then.

Windows-native builds

  • In general, setting up a C/C++ development environment is much easier in Linux/Unix or when utilizing Windows Subsystem for Linux than trying to compile "natively" on Windows. This is especially true when including third-party libraries where no standards exists where header include files or binary libraries can be found in the system. A native Windows build therefore is not recommended!
  • Ignoring this: for running a native Windows build, first download and install Build Tools for Visual Studio 2022 (Section "Tools for Visual Studio"). Ensure at a minimum the following will be installed: "Desktop development with C++".
  • After installation, open a "Developer PowerShell for VS 2022".
  • Navigate to your repository folder, create a build subdirectory and run CMake:
cd $env:USERPROFILE\workspace\fomss2024aud    # or whatever this is for you
mkdir build
cd build
cmake -G "NMake Makefiles" ..
nmake

Playgrounds

This section describes how to setup some playgrounds for additional programming languages and build environments.

Assembler & Qemu

  • Install assembler and qemu emulator. Add architecture if needed.
# dpkg --print-architecture
#dpkg --add-architecture armel

apt-get install crossbuild-essential-armel
apt-get install qemu-user
  • Cross-Build with CMake for ARM:
cmake .. -DCMAKE_TOOLCHAIN_FILE=../CMake-Toolchain-linux-arm.txt
  • Execute cross-compiled assembler with qemu-arm
qemu-arm bin/hello_world_asm_arm

Rust

  • Install rust compiler and package manager.
# package rustup in future Debian versions?
apt-get install rustc cargo rustfmt
  • Build rust files
cargo build
  • Run binaries
cargo run --bin hello
cargo run --bin hellorust
  • Run tests

Terraform

Not having a suitable build environment at hand? No problem! With today's hyperscalers, we're only a couple of commands away from building one. This is utilizing AWS here - could be any hyperscaler, though.

  • Installation: see Install Terraform
  • AWS Provider Documentation: AWS Provider
  • Ensure you have a local ssh key in ~/.ssh/id_ed25519.pub.
  • Running Terraform to setup a build environment:
cd  terraform
terraform init
terraform plan
terraform apply -auto-approve
# terraform destroy
  • This should setup a "plain" build environment with an installed docker.
  • At the end of the script, the instance_public_ip_addr will be displayed. Then you can login:
ssh admin@<xx.yyy.zz.dd>
# and on remote system:
mkdir workspace && cd workspace
git clone https://github.com/thorstendikmann/fomss2024aud.git
cd fomss2024aud/
  • ... and build:
mkdir build && cd build
cmake ..
make
  • ... or via Docker:
cd ~/workspace/fomss2024aud
make docker

Alternative Compilers

  • Instead of GCC, alternative compilers can be utilized (though not recommended). Let's install clang and the lld linker
apt-get install clang lld
  • Before running CMake the first time, we can enable clang via environment variables. lld as linker has to be selected manually via -D option.
export CC=/usr/bin/clang
export CXX=/usr/bin/clang++
cmake .. -DUSE_LLD=ON

References

Examples and some additional literature:

  • R. Sedgewick, Algorithms in C / C++, Parts 1-4,5. Addison-Wesley, 1998–2002.

  • R. Sedgewick and K. Wayne, Algorithmen und Datenstrukturen. Pearson, 2014.

  • J. Canning, A. J. Broder, and R. Lafore, Data Structures & Algorithms in Python. Addison-Wesley, 2023.

  • D. E. Knuth, The Art of computer programming. Volume 1-4. Addison-Wesley Professional, 1997–2022.

  • H. Knebl, Algorithmen und Datenstrukturen. Springer, 2019.

  • R. H. Güting and S. Dieker, Datenstrukturen und Algorithmen, Springer, 2018.

  • G. Pomberger and H. Dobler, Algorithmen und Datenstrukturen: eine systematische Einführung in die Programmierung. Pearson, 2008.

  • D. Harel and Y. A. Feldman, Algorithmics: The spirit of computing. Pearson Education, 2004.

  • B. N. Miller and D. L. Ranum, Problem solving with algorithms and data structures using Python. Franklin, Beedle & Associates Inc., 2011.

  • A. Solymosi and U. Grude, Grundkurs Algorithmen und Datenstrukturen in JAVA, Springer, 2017.

  • P. Widmayer and T. Ottmann, Algorithmen und Datenstrukturen. Springer, 2017.

  • B. W. Kernighan and D. M. Ritchie, The C programming language. Prentice Hall, 1988.

  • B. Stroustrup, Die C++ Programmiersprache. Addison-Wesley, 2000.

  • B. Stroustrup, Einführung in die Programmierung mit C++. Pearson Studium, 2010. Note: you will need std_lib_facilities.h

  • T. Theis, Einstieg in C. Rheinwerk Verlag, 2023.

  • R. Krooß and J. Wolf, C von A bis Z - das umfassende Handbuch. Rheinwerk Computing, 2023.

  • D. Bär, Schrödinger programmiert C++. Rheinwerk Computing, 2024.

  • U. Kaiser and M. Guddat, C/C++ - Das umfassende Lehrbuch. Galileo Press, 2014.

  • T. T. Will, Einführung in C++. Galileo Computing, 2023.

  • J. Ernesti and P. Kaiser, Python 3. Rheinwerk, 2023.

  • M. Inden, Einfach Python. dpunkt Verlag, 2022.

  • S. Elter, Schrödinger programmiert Python. Rheinwerk Verlag, 2021.

Toolchain