Local Development Environments#
This chapter give details on how to set up a standard development environment, including tools for writing and running software and for publishing technical documents.
System Tools#
This section reviews the fundamental tools in an Operating System that facilite setting up a development environment, namely:
a build toolchain and
a system package manager.
Mac#
Build Toolchain#
On Mac the primary build toolchain comes from the XCode package. This package includes:
Mac development system libraries
Compiler toolchains, particularly Apple’s version of the
clangcompilerA build environment via the Command Line
An graphical Integrated Development Environment
XCode is very likely neccessary for any software development you do on Mac, and for installing or running non-graphical software applications.
For ICHEC staff it is available in the ‘ICHEC Self Service’ application that is pre-installed on your Mac (don’t use the App Store). If downloading from there fails you can sign up for an Apple Developer Account (needs a credit card - won’t be charged) and download it from there.
Package Managers#
Homebrew is a third-party package-manager typically used on Mac - it is useful for installing packages via the CLI. You should regularly update your packages via the Homebrew CLI and be aware that applications are all provided by third-parties and not vetted by Apple in any way.
Installing packages takes the form:
brew install package_name
and you can (and regularly should) update brew and all packages with:
brew update && brew upgrade
You can clean Brew’s cache with:
brew cleanup
Brew is a good solution for general package management on Mac, however more advanced systems are available and worth considering if you are working on collaborative projects, such as Nix which allows for per-project management of build dependencies. This makes sure your project can be built in a clean environment by a collaborator without resorting to containers.
Linux#
Build Toolchain#
On Linux it may not be necessary to install a foundational toolchain as per Mac, however you will often end up needing at least a C/C++ compiler (gcc or clang being the most common) and build tooling including autotools, make and cmake. Linux distros often bundle some fundamental build tooling in a package group, like build-essential on Debian derived distros.
If you will only be working with, e.g. Python projects, then a Python interpreter may be sufficient for you.
Package Manager#
Linux distros typically comes with a package manager, for example apt on Debian derived systems or dnf on Red Hat like systems.
A newer generation of package managers and package distribution formats are becoming more popular on Linux now, including Nix and Guix which provide powerful isolated developer environments (like a more general Python Virtual Environment if familiar with that technology) and Flatpakas an isolated runtime environment often used by graphical applications.
Dotfile Management#
‘Dotfiles’ are config files for the tools used on your system. They are often preceeded by a ‘.’, like .tool_confg.yaml or are in a directory like ~/.config. It is useful to manage all of your dotfiles in one place, for example a git repository - which allows you to easily restore or roll back to previous configurations you use - or use the same configurations on multiple machines.
The GNU Stow tool can help you to manage your dotfiles by collecting them all together in one directory and then symlinking them to the approriate place on your system. Here is an example, which allows you to maintain a global gitignore for all of your projects. First create a repo for your dotfiles:
mkdir .dotfiles
Now create the following directory structure and ignore file:
cd .dotfiles
mkdir -p git/.config/git
touch git/.config/git/ignore
Here we are creating a stow package named ‘git’. Installing stow (on Mac brew install stow) and running it in the .dotfiles directory as stow git will copy the path git/ignore to ~/.config - which is the default location the git tool with look for it. Now you can fill out the ignore file as needed and push the .dotfiles repo. Over time you can build up other configs there - such as any customizations for your shell in a zshrc stow package.
If you want to use stow on a machine that you can’t install packages on you can build it with:
cd $DOWNLOAD_DIR
wget https://ftp.gnu.org/gnu/stow/stow-latest.tar.gz
tar -xvf stow-latest.tar.gz
cd stow-$VERSION
./configure --prefix ~/.local
make
make install
Finally, you will need to add Stow’s Perl module to Perl’s search paths, by setting $PERLLIB=$HOME/.local/share/perl5/5.32/in your shell runtime command (e.g. bashrc) (changing the perl version as needed from perl -version).
Some useful dotfiles include:
.bashrc
.zshrc
.vimrc
.nanorc
Some dotfiles can be introduced on a per-project basis also. Some that may be of interest include:
Text Editors and Integrated Development Evironments#
An Integrated Development Environment (IDE) can be useful if you are working in large or complicated codebases or prefer UI tools for code development. More recently they have included a powerful set of code linting and autocomplete features which can greatly ease software development, collaboration and improve code quality and reliability.
This sections covers some options:
GNU Emacs - free, open-source and highly customizeable text editor but with a high learning curve.
Microsoft’s Visual Studio Code - open source, multi-language and multi-platform IDE. Modern, feature-rich and customizeable. May be particularly useful for Microsoft supported web technologies, such as Typescript and C Sharp/.NET tooling.
however many more are available, some notable examples are:
XCode: May be particularly useful if working with Mac native applications and GUI programs
Neovim: Useful if you like vi/vim.
You may prefer, or be used to, working with a less-feature rich text editor like vi, notepad++ or vanilla vim. If you are experienced and feel productive this is fine. However if you are unsure or relatively new to software development it is advised that you try an IDE to get an idea of available features and to see if they help with your productivity.
Regardless of choice of IDE you should have access to the following features, which often come via plugins:
Syntax Highlighting
Code Completion
Context dialgos - with docstrings, arg lists and type info
Project and virtual environment awareness
Error highlighting
Auto-linting
Remote code development
Code launch and in-place debugging
Version control integration
GNU Emacs#
GNU Emacs is a free, open-source and highly customizeable text editor.
It has a text-focused rather than graphics-first interface.
Resources#
Emacs takes quite a bit of effort to set up and become comfortable with. Aside from the official manual below are some resources that may be of interest:
Installation#
Mac#
There are two brew packages, the graphical one comes via cask:
brew install --cask emacs
You can omit cask if just interested in the terminal version.
VS Code#
VsCode will run on Mac, Windows or Linux. VsCodium is a FLOSS fork that will run without telemetry, but with slightly fewer features.
Below are some general tips and notes for working with different languages.
Workspaces#
By default VsCode opens one window per project or ‘directory’. If you are used to having multiple projects open at once you can do ‘File->Add Folder To Workspace’ and then ‘File->Save Workspace As’ to establish a multi-project workspace.
This is very handy for e.g. having wiki notes to hand (like this handbook) while you work on code in different projects.
GitLab#
You can install the official GitLab extension to work with GitLab Issues/MRs and pipelines while in the IDE. After installting it will give details adding your account with your personal access tokens.
Python#
You can install the official MS Python extension as a VSCode plugin. Pylance is also recommended.
To resolve Python imports you will want make sure VSCode points to the virtual evironment you are working in. https://code.visualstudio.com/docs/python/environments
The easiest way to do this is to create the environment as ‘.venv’ at the top level of the workspace/source-tree - remembering to include it in your .gitignore file.
Remote Code#
You can work on a remote code checkout following this: https://code.visualstudio.com/docs/remote/ssh
Vi and Vim#
Vi and Vim are useful modal text editors which, once you learn the necessary commands, allow rich editing of text files including on remote systems. It is useful to know basic Vi commands to be comfortable working on content on remote systems.
Their functionality can be extended through a rich plugin system, such as through NeoVim.
You will want to set up a .vimrc file with at least some of:
syntax highlighting
line numbering
whitespace management
Below is a basic example:
syntax on # syntax highlighting
set shiftwidth=4 smarttab # tabbing whitespace
set expandtab
set tabstop=8 softtabstop=0
set number # line numbers
:inoremap <S-Tab> <C-V><Tab> # literal tab input
You can copy this file to any machine you access remotely to get a comfortable editing experience there - the dotfile management section gives some tips on doing this in a repeatible way for all tools.
Nano#
Nano is a basic terminal-based text editor which can be useful when working with remote systems or making quick edits in the shell. It is simple to use and get started with, however it is probably worth investing time learning some Vi commands to get a richer shell editing experience.