Skip to content

2. Dev Setup

Jump to bottom
Wanda Boyer edited this page Oct 17, 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

Coming soon: installing MinGW and optionally MSVC

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

Coming soon: installing Python 3.12 on Windows

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-get update && sudo apt-get -y upgrade && sudo apt-get 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))
  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.
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. Coming soon: installing Python 3.12 on MacOS
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 black Python formatter extension.

Debug and Release configurations within tasks.json and launch.json for C/C++ applications

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 these scripts.

More details coming soon

Python linting and formatting for the TestSupport scripts

The settings.json customizes the behaviour of the pylint and black VSCode extensions; see Issue #100 for more context.

More details coming soon

Eclipse

One must 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

More details coming soon

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

Clone this wiki locally