Skip to content

2. Dev Setup

Jump to bottom
Wanda Boyer edited this page Oct 28, 2024 · 44 revisions

Introduction

Originally, the README.md contained instructions for how to set up a development environment for the edge-addition-planarity-suite on Windows using the Eclipse IDE (see README.md from commit b4063b). Support was extended to using Visual Studio Code on Windows 10 (both MinGW gcc and MSVC cl) and MacOS Sequoia 15.0 (clang) with the testing of PR #16, and subsequently to include Debian Linux 12.7 with the testing of PR #58. The most recent Visual Studio Code configuration files were updated in PR #92 to reflect the new project structure described by Epic #91.

For simplicity and maintainability of the documentation, support for the Eclipse IDE has been deprecated; the following instructions now only refer to setting up Visual Studio Code for development purposes.

Supported Platforms

Windows

  1. Install your chosen compiler toolchain:
    1. To install MinGW 32, download and run mingw-get-setup.exe from here and then use the MinGW Installation Manager to install C and C++, GDB, MSYS, and any other packages you may want; with the Basic Setup tab selected, mark the mingw-developer-toolkit-bin (also marks msys-base-bin meta package for installation) and mingw32-base-bin meta packages for installation, then under the Installation menu item, select "Apply Changes". Finally, ensure your gcc is accessible from the command line by adding C:\MinGW\bin to the system PATH.
    2. To install the MSVC compiler toolchain, follow the third step of Configure VS Code for Microsoft C++ to use the Visual Studio Installer to install the "Desktop development with C++" Visual Studio Build Tools workload. One must use the Developer Command Prompt to use the MSVC compiler toolchain, as other shells won't have the appropriate environment variables set; if you choose to use VSCode with MSVC cl, you must open the Developer Command Prompt, navigate to the edge-addition-planarity-suite repository root, and run VSCode by executing: 
      code .
  2. To install Python 3.12 on Windows 10:
    1. Follow 4.1.1. Installation steps using the Python 3.12.7 Windows 64-bit installer from the Python Releases for Windows page.
      • 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.
  3. Follow Install git on Windows
  4. 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++.
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

  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. 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.
  3. To build Python 3.12 from source on Debian Linux, please follow the Python documentation page Building Python; in particular, please ensure that you run make altinstall so that you do not override the system python3 binary.
    • 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 for instructions on how to get all build dependencies on Linux. 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.
  4. To install Visual Studio Code on Linux, follow Visual Studio Code on Linux - Installation, and then Using C++ on Linux in VS Code.
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

  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 Python 3.12 on MacOS, download the Python 3.12.7 macOS 64-bit universal2 installer from the Python Releases for macOS, or from the Python 3.12.7 release page.
  7. To install Visual Studio Code on MacOS, follow Visual Studio Code on macOS - Installation, and then Using Clang in Visual Studio Code.
Installing Python 3.12 using Homebrew (NOT recommended)
  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 python@3.12 by running the install command: 
    % brew install python@3.12
  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/python@3.12/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.

Working with Visual Studio Code

GitHub Forking Workflow for the edge-addition-planarity-suite

  1. Fork the edge-addition-planarity-suite repository
  2. Clone your fork for local use via the command-line
    • N.B. If you don't wish to use the command-line, follow Clone a repository locally to clone your fork within Visual Studio Code. After you have chosen your fork to clone locally, if prompted "Do you trust the authors of the files in this folder?", select "Yes, I trust the authors."
  3. If you plan on contributing to the project, create a feature branch on the local copy of your fork (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 do this, you must either:
    1. 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. 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.
  4. 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.

Installing extensions

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

  1. C/C++ Extension Pack - ms-vscode.cpptools-extension-pack
  2. Python - ms-python.python
  3. Pylint - ms-python.pylint
  4. Black Formatter - ms-python.black-formatter
  5. GitLens - eamodio.gitlens

Final setup steps

One must run the edge-addition-planarity-suite/devEnvSetupAndDefaults/devEnvSetupScript.sh (to be added in forthcoming PR to satisfy Issue #89) to copy the bespoke tasks.json and launch.json into the .vscode directory at the root of the project. These configuration files allow users to build and run/debug the planarity executable on Windows (MinGW gcc and MSVC cl), Debian Linux (gcc), and MacOS (clang), and also enable one to debug the Python TestSupport scripts. Additionally, this script copies a bespoke settings.json to configure the pylint as well as the black Python formatter extension.

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.

N.B. Issue #100 will entail filling out further detail of this 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.

Clone this wiki locally