CONTRIBUTING

About this Guide

This guide includes steps assuming you're starting a project. If this is not your first project in the environment, you may have already completed many of these steps.

Using this template repository

See Creating a Repository from a template

Setting up a development environment

Get to a Unix Prompt

Mac Users: Congratulations. You have a Unix prompt.

Windows Users:

• Install Debian or Ubuntu under WSL through the Windows store.
• Or SSH into a remote Linux development system.

Tip: I had to set my WSL user edward password from PowerShell outside WSL, due to this bug https://github.com/microsoft/terminal/issues/1823

PS> wsl -d Debian -u root passwd edward
New password:
Retype new password:
passwd: password updated successfully

Packages to Manage Development Environments

These steps are all completed inside of a Linux/Unix command prompt.

Tip: Windows WSL tips in this guide are not needed on Mac or remote Linux systems.

These steps were captured on Debian WSL2 on Windows 10.

Tip: Some commands, specifically apt, will differ on a Mac computer. Sometimes apt can be replaced with brew for Mac use.

1. Install common packages

   These packages are necessary to install brew and to install versions of Python once pyenv has been installed.

   sudo apt-get update; sudo apt-get -y install \
   git make build-essential libssl-dev zlib1g-dev \
   libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
   libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
   libffi-dev liblzma-dev

2. Install Brew (without sudo)

   Use the curl command provided at https://https://brew.sh to run the installer provided in the HEAD commit of the Homebrew project.

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

   Tip: Run the commands recommended by brew to update ~/.profile

   Confirm that brew is installed and available with which brew:

   $ which brew
   /home/linuxbrew/.linuxbrew/bin/brew

3. Install PyEnv:

   brew update && brew upgrade && brew install pyenv

Tip: Create a file /etc/wsl.conf with the following to remove Windows executables from the path in WSL. This prevents errors from running the wrong copy of tools, like git that may be installed both inside and outside WSL.

[interop]
appendWindowsPath = false

And Consider adding these aliases to ~/.bashrc for convenience:

alias code="/mnt/c/Program\ Files/Microsoft\ VS\ Code/bin/code"
alias clip="/mnt/c/Windows/system32/clip.exe"
alias paste="/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe -noprofile -command Get-Clipboard"

Alias usage:

cat ./text.txt | copy  # Copy to the Windows Copy/Paste buffer
paste > ./text.txt     # Paste from Windows
code ./text.txt        # Open a file in Windows VSCode editor
code .                 # Open the current folder in Windows VSCode

Set Python Versions with PyEnv

Install and set the Python version for the current project

# Install the needed Python version
pyenv install 3.9.11
# Set the local folder to use the needed Python version
cd /data/src/project1
pyenv local 3.9.11
# Confirm the Python version in use before creating a virtual environment
python -V
python -m venv venv
source ./venv/bin/activate
# Install required packages for the local project
pip install -f requirements.txt

Tip: Check the project Makefile for helper commands. Once python -V returns the correct version, the Makefile may be able to do the rest.

Troubleshooting

Check your .bashrc for stray additions. At one point we had CC set.