Skip to content

2. Dev Setup

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

N.B. This is an incomplete draft version of the development environment setup notes

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.

Supported Platforms

Windows

To install MinGW 32, download and run mingw-get-setup.exe from here and then use the package installer to install C and C++, GDB, MSYS, and any other packages you may want. Then, ensure your gcc is accessible from the command line by adding C:\MinGW\bin to the system PATH.

N.B. These instructions will be revised to cover installing MinGW 64 as a part of Issue #102 - Add support for MinGW 64 and deprecate MinGW 32

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 .

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

If you follow 4.2. The Microsoft Store package, you may end up installing a higher version of Python than that 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

  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
    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))
    • 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.
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

% which clang
/usr/bin/clang

% which lldb
/usr/bin/lldb

% which leaks
/usr/bin/leaks
    Where clang is the compiler, lldb is the debugger, and 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)
  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.

N.B. Issue #111 has been created to investigate whether we should be using the clang installed via homebrew rather than that which is installed with the Xcode command line tools

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.

Supported IDEs

Visual Studio Code

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++.

To install Visual Studio Code on MacOS, follow Visual Studio Code on macOS - Installation, and then Using Clang in Visual Studio Code.

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

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 
    Name: C/C++ Extension Pack
Id: ms-vscode.cpptools-extension-pack
Description: Popular extensions for C++ development in Visual Studio Code.
Version: 1.3.0
Publisher: Microsoft
VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools-extension-pack
  2. Python - ms-python.python 
    Name: Python
Id: ms-python.python
Description: Python language support with extension access points for IntelliSense (Pylance), Debugging (Python Debugger), linting, formatting, refactoring, unit tests, and more.
Version: 2024.14.1
Publisher: Microsoft
VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=ms-python.python
  3. Pylint - ms-python.pylint 
    Name: Pylint
Id: ms-python.pylint
Description: Linting support for Python files using Pylint.
Version: 2023.10.1
Publisher: Microsoft
VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=ms-python.pylint
  4. Black Formatter - ms-python.black-formatter 
    Name: Black Formatter
Id: ms-python.black-formatter
Description: Formatting support for Python files using the Black formatter.
Version: 2024.2.0
Publisher: Microsoft
VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter
  5. GitLens - eamodio.gitlens 
    Name: GitLens — Git supercharged
Id: eamodio.gitlens
Description: Supercharge Git within VS Code — Visualize code authorship at a glance via Git blame annotations and CodeLens, seamlessly navigate and explore Git repositories, gain valuable insights via rich visualizations and powerful comparison commands, and so much more
Version: 15.5.1
Publisher: GitKraken
VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens

Finally, 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.

Eclipse

N.B. These instructions were originally a part of README.md (commit # b4063bf) and refer to older software versions; Issue #103 will entail updating these instructions.

To set up the Eclipse IDE on Windows 10:

  1. Install a recent version of the Java JDK (such as Java version 14 or higher)
  2. Ensure that you set the JAVA_HOME system environment variable (e.g. to c:\Program Files\Java\jdk-14.0.1)
  3. Ensure that you add %JAVA_HOME%\bin to your system PATH
  4. Install Eclipse, such as the "Eclipse IDE for Enterprise Java Developers"
  5. In Eclipse, and install the C Development Tools (CDT)
    1. In Eclipse, choose the menu option Help > Install New Software
    2. Choose to work with the main repository (e.g. 2020 - 06 - http://download.eclipse.org/releases)
    3. Under Programming Languages, choose C/C++ Autotools, C/C++ Development Tools, C/C++ Development Tools SDK, C/C++ Library API Documentation Hover Help, and C/C++ Unit Testing Support
  6. Run the edge-addition-planarity-suite/devEnvSetupAndDefaults/devEnvSetupScript.sh (N.B. Will be added in forthcoming PR to satisfy Issue #89) to copy defaults for the following files:
    • edge-addition-planarity-suite/.project
    • edge-addition-planarity-suite/c/.project
    • edge-addition-planarity-suite/c/.cproject

Working with the Code in the Development Environment

VSCode

Coming soon

Eclipse

Coming soon

Making the Distribution

N.B. The following process has been tested on Debian Linux 12.7.0 and Windows 10 22H2 with MinGW 32

Coming soon

Clone this wiki locally