Skip to content

Environment Setup

Before you start hacking away, we have to get our development environments setup right. Fortunately, this project is fairly light on system requirements and there are only a few application/program dependencies.

We've all been plagued by the "it works on my computer problem" at some point.

Note

If you want to jump straight to installing things, feel free to pop to the "What Should I Install" section. Most of the information here is also covered in the readme.md file located in the root of the repository.

Quick Overview

The Upenn Embedded Systems Handbook uses MkDocs as its documentation management system. More specifically we use the Material by MkDocs variant of this tool by squidfunk. We won't go into the specifics of how this tool works (there's a great video for that here) but the takeaway is that it allows all of the content you're viewing to be easily accessible and modifiable using nothing more than markdown and a little HTML when necessary. From there we use GitHub Pages to deploy the project with a public URL for the world to see! Massive thanks maintainers and supporters of these tools. Without them, this project would not be possible.

As the project grew, we've added a few tools and scripts to help automate parts of the project. At the time of writing this includes:

  • Integrating the deployment into Make build system
  • Python scripting for static page generation
  • GitHub API call to retrieve list of contributors

Cloning the Reopository

TODO: Do we need steps for how to pull from git?

What Should I Install?

To keep it brief, there are only two things you need to being working on this project: 1. GNU Make 2. Python 3.8+

Support Python Versions Note

Python 3.8 is the minimum required version at the time of writing. Using newer versions of Python (i.e. 3.12) is acceptable. However, using a newer version of python may require the creation of a python virtual environment which shall not be covered in this section. See see PEP 668 for more information.

GNU Make

Download and Install GNU make using the respective link for your operating system

  1. Windows
  2. Mac OS
  3. Linux

Python Version 3.8

Download and Install Python 3.8.X using the respective link for your operating system

  1. Windows
  2. Mac OS
  3. Linux

Install Python Dependencies

In the root of the repository is a requirements.txt file which can be used with pip to install all required packages and dependencies system-wide. This is the recommended method of installing the necessary modules although manual installs shall also suffice.

From the root of the repository, open a terminal instance and type the following: 

pip install -r requirements.txt

If you want to setup the project in a virtual enviornment, please refer to the following guide here. Note that you will will likely want to activate the virutal environment before starting development.