Skip to content

2. Dev Setup

Jump to bottom
John M. Boyer edited this page Jan 30, 2025 · 34 revisions

Introduction

A variety of development environments can be used to work with the Edge Addition Planarity Suite code. This documentation details how to set up and use Visual Studio Code (VSCode) because it provides the most consistent development experience across versions of Linux, Mac OS, and Windows, especially including a functioning debugger on all platforms and superior Git plugins to facilitate source code control. For many years, the Eclipse IDE has also been used for development in this project, but Visual Studio Code is now the recommended development platform.

Installing Dev Dependencies

Platform-specific setup instructions

Windows

Installing (a) compiler toolchain[s], autotools, Git for Windows, VSCode, and Python 3.12

  1. Install your chosen compiler toolchain:

    1. To install MinGW-w64, follow the VSCode instructions on Installing the MinGW-w64 toolchain. While you're in the neighborhood of updating your Environment Variables to add C:\msys64\ucrt64\bin to your PATH User Variable, also add C:\msys64\usr\bin because this will allow you to run the MSYS2 utilities from the command prompt, including spawning a bash session. Additionally, if you plan to build the distribution using MSYS2, then install autotools by running the following in the MSYS2 UCRT64 shell (the same shell, or relaunch the MSYS2 UCRT64 app, if necessary): 
      pacman -S "${MINGW_PACKAGE_PREFIX}-autotools"
      For more information, see Autotools.
    2. To install the MSVC compiler toolchain, instead of or in addition to using MinGW-w64, follow the third step of Configure VS Code for Microsoft C++. In this step, you use the Visual Studio Installer (not to be confused with the VSCode installer) to install the "Desktop development with C++" Visual Studio Build Tools workload.

  2. Follow Install git on Windows

  3. To install Visual Studio Code on Windows, follow Visual Studio Code on Windows - Installation, and then depending on which compiler toolchain you have installed, follow either Using GCC with MinGW or Configure VS Code for Microsoft C++.

    • NB: The preferred method of running VSCode is based on using the Developer Command Prompt, as described in the Working with the Code section below. Some VSCode users prefer instead to simply run the Visual Studio Code app directly. While this can work for MinGW compiler users, it does not work with the MSVC compiler toolchain, which requires environment variable settings only made by the Developer Command Prompt.

  4. (OPTIONAL) To install Python 3.12 on Windows (if you need to run code in TestSupport):

    1. Follow 4.1.1. Installation steps using the Python 3.12.7 Windows 64-bit installer from the Python Releases for Windows page. In particular, make sure to check "Add python.exe to PATH", and "Disable path length limit"
      • N.B. Unless you choose to customize the installation, you will only install Python for the current user; the Path variable under "User variables for " will be prepended with the user-level Python installation directory (i.e. a subdirectory of %LOCALAPPDATA%)
    2. Open “Manage App Execution Aliases” through the Start menu and toggle both python3.exe and python3.exe to off,
    3. Confirm successful installation by opening a command prompt and checking the output from python --version: 
      C:\Users\wbkbo>python --version
Python 3.12.7
    • N.B. If you follow 4.2. The Microsoft Store package to install Python, you may end up installing a higher version than that with which the TestSupport/planaritytesting package has been tested.
Creating a Windows 10 22H2 VM using VirtualBox

If you are on a Windows device and wish to create a Windows 10 Home 22H2 virtual machine to contain your development environment, you can download the Windows 10 Media Creation tool which will help you create an .iso file. Otherwise, you may download the .iso file directly from the Windows 10 Home 22H2 ISO Download page.

Debian Linux

Installing build dependencies, Git, VSCode, and building Python 3.12 from source

  1. Ensure your username is part of the sudoers group; if not, then follow the advice in the replies to this Unix StackExchange post

  2. Check the contents of your /etc/apt/sources.list to ensure the location of the source packages (including URL, distribution name and component name) are uncommented:

    $ cat /etc/apt/sources.list
# See sources.list(5) manpage for more information
# Remember that CD-ROMs, DVDs and such are managed through the apt-cdrom tool.
deb http://deb.debian.org/debian bookworm main contrib non-free non-free-firmware
deb http://deb.debian.org/debian bookworm-updates main contrib non-free non-free-firmware
deb http://deb.debian.org/debian-security bookworm-security main contrib non-free non-free-firmware

# Uncomment if you want the apt-get source function to work
deb-src http://deb.debian.org/debian bookworm main contrib non-free
deb-src http://deb.debian.org/debian bookworm-updates main contrib non-free
deb-src http://deb.debian.org/debian-security bookworm-security main contrib non-free

    If not, you may edit the file with sudo vi /etc/apt/sources.list to manually add these sources; see the SourcesList documentation, the Mirror List, and Debian mirrors backed by Fastly CDN site for more info.

  3. Run the following command

    sudo apt update && sudo apt -y upgrade && sudo apt install -y build-essential gdb autotools-dev git-all

    To install build dependencies (i.e. the build-essential metapackage, which includes gcc but doesn't include gdb, as well as the GNU Autotools (see the Autotools FAQ and the Debian AutoTools home for more info)). Finally, we must install git-all (see Install git on Linux - Debian/Ubuntu)

    • N.B. It is preferable to use apt rather than apt-get to update, upgrade, and install packages due to more sophisticated package search, system memory cleanup, and dependency resolution; please see the AWS docs on What’s the Difference Between apt and apt-get? for more in-depth justification.

  4. To install Visual Studio Code on Linux, follow Visual Studio Code on Linux - Installation, and then Using C++ on Linux in VS Code.

  5. (OPTIONAL) To run the TestSupport/planaritytesting Python package scripts, one must build Python 3.12 from source on Debian Linux:

    1. Run 
      sudo apt build-dep -y python3 && sudo apt install -y pkg-config
      • N.B. Although the TestSupport/planaritytesting package doesn't depend on extension modules that impose further requirements of development headers for additional libraries, it might be prudent to follow the Python Developer's Guide - Build Dependencies and to run this additional command: 
        sudo apt install -y build-essential gdb lcov pkg-config \
libbz2-dev libffi-dev libgdbm-dev libgdbm-compat-dev liblzma-dev \
libncurses5-dev libreadline6-dev libsqlite3-dev libssl-dev \
lzma lzma-dev tk-dev uuid-dev zlib1g-dev
        If you decide to install these dependencies after having initially built and installed Python 3.12 from source, you'll have to re-run configure and make altinstall.
    2. Download the Python-3.12.7.tgz source file, navigate to the download directory, and extract it by running: 
      tar -xvzf Python-3.12.7.tgz
    3. Run: 
      cd Python-3.12.7 && ./configure && make && sudo make altinstall
      (See the Python documentation page Building Python for more info)
    4. Confirm your Python installation: 
      $ python3.12 --version
Python 3.12.7

$ which python3.12
/usr/local/bin/python3.12
      • N.B. This means that the 3. Test Support scripts must be run from the shell with Python alias python3.12
Creating a Debian Linux 12.7 VM using VirtualBox

If you wish to create a Debian Linux VM to contain your development environment, you can get the most recent version of Debian Linux from the Debian Downloads page; however, the edge-addition-planarity-suite has been tested on Debian 12.7.0, the netinst CD image .iso for which may be obtained from Installing Debian 12.7 (Bookworm). If you are using VirtualBox to set up your VM, follow a guide like How To Install Debian 12 on VirtualBox, which includes instructions for how to set up VirtualBox Guest Additions on the Debian Linux VM; there are alternate instructions for how to install VirtualBox Guest Additions on the VM provided by the Debian Wiki: Installing the Guest Additions on a Debian VM - Debian 10 "Buster", Debian 11 "Bullseye", and Debian 12 "Bookworm". If your sources.list doesn't contain the expected package mirrors, you can copy a default version by running:

sudo cp /usr/share/doc/apt/examples/sources.list /etc/apt/sources.list

Recommended in this reply to a Unix StackExchange post.

MacOS

Installing Xcode command-line tools, VSCode, and Python 3.12
  1. Open a terminal window and type: 
    % xcode-select --install    
xcode-select: note: install requested for command line developer tools
  2. A new prompt will open outside the terminal window; click 'Install'
  3. Agree to the Command Line Tools License Agreement
  4. A new prompt will open indicating the progress as the software is downloaded
  5. Verify that Xcode command line tools were correctly installed and the requisite utilities are present: 
    % xcode-select -p     
/Applications/Xcode.app/Contents/Developer

% clang --version
Apple clang version 16.0.0 (clang-1600.0.26.4)
...

% lldb --version
lldb-1600.0.39.3
...

% leaks --help
leaks: Search through a process for leaked memory.
...

% git --version
git version 2.39.5 (Apple Git-154)
    Where clang is the compiler, lldb is the debugger, leaks is a command-line tool for finding memory leaks (see the 3. Test Support wiki page section on Automating memory checking on MacOS using leaks), and git is the source control utility required to interact with this repository as a contributor
  6. To install Visual Studio Code on MacOS, follow Visual Studio Code on macOS - Installation, and then Using Clang in Visual Studio Code.
  7. (OPTIONAL) To run the TestSupport/planaritytesting Python package scripts, one must install Python 3.12 on MacOS using the Python 3.12.7 macOS 64-bit universal2 installer available from the Python Releases for macOS, or from the Python 3.12.7 release page.

N.B. One may install Python 3.12 via Homebrew, but these steps are not recommended and are only included for reference if you need to get yourself out of a pickle:

  1. Follow The Hitchhiker's Guide to Python instructions for Installing Python 3 on Mac OS X. This recommends using homebrew to install Python 3 using the command brew install python; however, you can specify [email protected] by running the install command: 
    % brew install [email protected]
  2. In order to ensure the proper environment variables are set for homebrew, you must add the following to your ~/.zprofile file: 
    eval "$(/opt/homebrew/bin/brew shellenv)"
    Then run source ~/.zprofile
  3. Check what the aliases for python and python3 correspond to by typing the following: 
    % python --version
zsh: command not found: python

% which python
python not found

% python3 --version
Python 3.9.X             <----- INSTALLED BY xcode-select --install

% which python3
/usr/bin/python3

% python3.12 --version
Python 3.12.7

% which python3.12
/opt/homebrew/bin/python3.12
  4. To set the alias python and python3 to correspond to the python3.12 binary, add the following to your ~/.zprofile file: 
    export PATH=/opt/homebrew/opt/[email protected]/libexec/bin:$PATH
    Then run source ~/.zprofile.
    • N.B. If you do not follow this step, then scripts in the TestSupport/planaritytesting package (see 3. Test Support) must be run using python3.12 as the interpreter alias
Creating a MacOS Sequoia 15.0 VM using UTM

If you wish to create a MacOS VM to contain your development environment, visit the Apple Developer Download page and sign in using your Apple ID; then, search for MacOS (i.e. Sequoia 15.0) and click the link labelled Mac computers with Apple silicon to download the .ipsw restore image. Then, download UTM and install this system emulator. Finally, follow their instructions for How to set up a MacOS Guest using the .ipsw previously downloaded.

Installing VSCode Extensions

Once you have installed VSCode on your chosen platform(s), Browse for extensions and choose to install:

  1. C/C++ Extension Pack - ms-vscode.cpptools-extension-pack
  2. GitLens - eamodio.gitlens
  3. (OPTIONAL) If you wish to run and/or develop the TestSupport/planaritytesting Python package:
    1. Python - ms-python.python
    2. Pylint - ms-python.pylint
    3. Black Formatter - ms-python.black-formatter

Working with the Code

Fork & Clone the Code

  1. Fork the edge-addition-planarity-suite repository (use the Fork button on the Code panel)

  2. Clone your fork for local use, either:

    1. Via the command-line, or
    2. With the Visual Studio Code interface, as follows:
      • Before running VSCode, create a directory to contain your cloned git repositories (if you have not already done so); for example, <User Home directory>/git
      • Launch a terminal session, then change directories into the directory to contain cloned git repositories, and execute code . 
        cd <User Home directory>/git
code .
        • N.B. If you're on Windows using the MSVC compiler toolchain, use the Developer Command Prompt installed by the Visual Studio Installer to run this sequence of commands
      • Copy the https URL for the project using the green Code button on the Code panel of the edge-addition-planarity-suite
      • Press Clone Git Repository... on the Welcome page in Visual Studio Code, and paste the https URL into the Clone from GitHub edit box, and hit Enter.
        • N.B. If prompted "Do you trust the authors of the files in this folder?", select "Yes, I trust the authors."
      • In the succeeding file dialog, navigate to and select the pre-created <User Home directory>/git subdirectory in the file dialog, then press Select Repository Destination (the code will be cloned into a subdirectory of <User Home directory>/git called edge-addition-planarity-suite)
      • Press Open when prompted to open the project in the workspace

Once you have cloned the project code, it is best to shut down Visual Studio Code and so that you can run the Development Environment Setup script (see next subsection).

Final Dev Env Setup

Before beginning to work with the code for the first time, it is necessary to run the development environment setup script, devEnvSetupScript.sh. This script exists because the Git repository includes default versions of development environment configuration files that developers may want to modify during development work without creating a changed file to commit. The script copies the configuration files into their correct locations, and the .gitignore ignores them in those locations, so the developer can modify them at will.

These editable development environment configuration files include the tasks.json and launch.json files in the .vscode directory in the local directory root of the project. These configuration two files allow users to build and run/debug the planarity executable on Windows (MinGW gcc and MSVC cl), Debian Linux (gcc), and MacOS (clang). They also enable one to debug the Python TestSupport scripts. The development environment setup script also copies a settings.json file into the .vscode directory, which provides configuration for the pylint and black VSCode extensions, as well as copies the custom .pylintrc into the TestSupport/planaritytesting Python package.

1. Run Dev Env Setup Script: In your chosen terminal (use MSYS2 UCRT bash or Git Bash in Windows), navigate to the devEnvSetupAndDefaults directory and then run the devEnvSetupScript.sh:

    cd <User Home directory>/git/edge-addition-planarity-suite/devEnvSetupAndDefaults
    ./devEnvSetup.sh

2. Restart VSCode

  1. Run Developer Command Prompt
  2. Change directory to <User Home directory>/git/edge-addition-planarity-suite (not just <User Home directory>/git)
  3. Execute code .
Debug and Release configurations within tasks.json and launch.json for C/C++ applications

To debug the planarity executable within VSCode:

  1. Update the args array of your platform's Debug configuration to contain a quotes-enclosed comma-separated list of the command-line parameters; for example, from the "C/C++: (Windows) [Debug] gcc.exe build and debug planarity project" in launch.json: 
                ...
            "args": [
                ...
                // Command: `planarity -test <samplesDir>`
                // "-test",
                // "${workspaceFolder}\\c\\samples"
            ],
            ...
  2. Add desired breakpoints
  3. Ensure a .c file's tab has focus before clicking the dropdown next to the play button icon ("[Run|Debug] C/C++ File") in the top right of the VSCode editor and select "Debug C/C++ File"
  4. Select the launch configuration corresponding to your current platform and compiler toolchain; please read the following for the correspondence between tasks.json build tasks and launch.json run/debug configurations.

Windows

  • For MinGW gcc, refer to Using GCC with MinGW sections Run helloworld.cpp and Customize debugging with launch.json
    • C/C++: (Windows) [Debug] gcc.exe build planarity project in tasks.json is the preLaunchTask for C/C++: (Windows) [Debug] gcc.exe build and debug planarity project in launch.json
    • C/C++: (Windows) [Release] gcc.exe build planarity project in tasks.json is the preLaunchTask for C/C++: (Windows) [Release] gcc.exe build and run planarity project in launch.json
  • For MSVC cl, refer to Configure VS Code for Microsoft C++ sections Run helloworld.cpp and Customize debugging with launch.json. N.B. You must run VSCode from the Developer Command Prompt, otherwise you won't have the appropriate environment variables set to build using MSVC cl nor to debug; see section Check your Microsoft Visual C++ installation
    • C/C++: (Windows) [Debug] cl.exe build planarity project in tasks.json is the preLaunchTask for C/C++: (Windows) [Debug] cl.exe build and debug planarity project in launch.json
    • C/C++: (Windows) [Release] cl.exe build planarity project in tasks.json is the preLaunchTask for C/C++: (Windows) [Release] cl.exe build and run planarity project in launch.json

Linux

  • For gcc on Linux, refer to Using C++ on Linux in VS Code sections Run helloworld.cpp and Customize debugging with launch.json
    • C/C++: (Linux) [Debug] gcc build planarity project in tasks.json is the preLaunchTask for C/C++: (Linux) [Debug] gcc build and debug planarity project in launch.json
    • C/C++: (Linux) [Release] gcc build planarity project in tasks.json is the preLaunchTask for C/C++: (Linux) [Release] gcc build and run planarity project in launch.json

MacOS

Debug configuration for Python TestSupport scripts

Please see the 3. Test Support wiki page for more context on the scripts within the TestSupport/planaritytesting package, in particular their command-line parameterization; to debug one of these scripts using the "Python Debugger: Current File with Arguments" configuration:

  1. Update the args array to contain a quotes-enclosed comma-separated list of the command-line parameters: 
                ...
            "args": [
                // Args to test test_table_generation_with_numInvalidOK.py 
                // "-n",
                // "5,8",
                // "-c",
                // "3",
                // "p",
                // "o"
            ]
            ...
  2. Open the target Python script
  3. Set any desired breakpoints
  4. Ensure the tab corresponding to the target Python script has focus
  5. Click the dropdown next to the play button icon ("Run Python File") in the top right of the VSCode editor and select "Python Debugger: Debug using launch.json"
  6. Select "Python Debugger: Current File with Arguments"

For greater context on how to debug Python applications in VSCode using the "Python Debugger: Current File with Arguments" configuration in launch.json, please see Python debugging in VS Code. In particular, the section Set configuration options details the keys and possible values to augment the Python debugging experience.

Python linting and formatting for the TestSupport scripts

The settings.json customizes the behaviour of the pylint and black VSCode extensions:

{
    "[python]": {
        "editor.rulers": [
            79,
            99
        ],
        "editor.defaultFormatter": "ms-python.black-formatter",
        "editor.formatOnSave": true
    },
    "editor.formatOnSave": true,
    "editor.renderWhitespace": "all",
    "files.autoSave": "afterDelay",
    "python.analysis.typeCheckingMode": "basic",
    "black-formatter.cwd": "${workspaceFolder}/TestSupport/planaritytesting",
    "black-formatter.args": [
        "--line-length=79",
        "--target-version=py312"
    ],
    "pylint.args": [
        "--rcfile=${workspaceFolder}/TestSupport/planaritytesting/.pylintrc"
    ]
}

We set the default formatter for Python code to black by assigning ms-python.black-formatter to editor.defaultFormatter, and since we want to restrict the black formatter to only format the planaritytesting Python package, black-formatter.cwd is set to ${workspaceFolder}/TestSupport/planaritytesting.

For linting, a default .pylintrc file was generated (see pylint Documentation - Configuration), and invalid-name was added to the disabled list of the [MESSAGES CONTROL] section due to instances of camelcase coming from the planarity C side (e.g. numInvalidOKs as a variable name). This default .pylintrc is copied from the devEnvSetupAndDefaults/.vscode directory when one runs the devEnvSetup.sh with cwd as devEnvSetupAndDefaults/, and is consumed by the pylint extension by setting the --rcfile to ${workspaceFolder}/TestSupport/planaritytesting/.pylintrc in the pylint.args key of settings.json.

See Issue #100 for the original investigation into Python formatting and linting configuration). For greater context on the configuration for linting and formatting specified in settings.json, please refer to Linting Python in Visual Studio Code and Formatting Python in VS Code.

Contributing Code

  1. If you plan on contributing to the project, create a feature branch on the local copy of your fork (e.g. in VSCode, follow the documentation on Branches and Tags; if using GitLens (See below), refer to GitLens - Sidebar - Source Control and Branches View), regularly committing and pushing to your fork on GitHub, and ensure that any upstream changes to the base repository are merged into your feature branch.

    To ensure your feature branch is kept up-to-date with the most recent changes on master of the base repository, you must either:

    1. Within VSCode: Follow Syncing a fork branch from the web UI, switch to your master branch within VSCode, fetch and pull the changes that were synced from the base repository into your fork, and then switch to your feature branch and merge your local master into that branch.
    2. Command-Line: Set the upstream URL on the command-line to that of the edge-addition-planarity-suite base repository, and then regularly sync your fork, merging any upstream changes synced to your master into your feature branch.

  2. When you are ready to propose your changes, please create a Pull Request from the branch of your fork to the graph-algorithms:edge-addition-planarity-suite's master branch.

Clone this wiki locally