Getting started with Pytch development

This section explains how to get a development environment set up to work on Pytch itself.

Requirements

Git

For fetching and working with the source code and related files.

Python 3

The build tools, for example for building tutorials, are based on version 3 of Python. Note that on macOS, you need to have run the Install Certificates command, as is suggested by the Python installer, to ensure that the Python’s package installer pip can make secure connections. The command python must launch Python 3 — on Ubuntu, you can install the package python-is-python3 to achieve this.

Poetry

For managing Python projects and their dependencies. See its web page for installation instructions. You might have to manually update your PATH, for example by adding a line to your .bashrc file.

Node.js

For building the Skulpt-based VM, and the webapp. Pytch is developed using the v18 Long Term Support release of Node.js. The npm package manager is also required, which usually comes bundled with Node.js. Your operating system might come with different versions of node and/or npm. A convenient way to manage multiple node/npm versions on your machine is to use the nvm tool. After installing nvm, you can do nvm install v18 to set up the appropriate version of node.

Docker

Optional, for easy testing of a built zipfile.

The tmux terminal multiplexer

The dev-server script requires tmux, which is available for Linux and Mac machines. It is also available on Windows, under the Windows Subsystem for Linux (see below).

GNU coreutils

The build scripts use realpath from GNU coreutils. Most Linux-based systems will install these tools by default. On macOS you may need to run brew install coreutils.

(This list might be incomplete; please let us know of any gaps.)

Source code

Pytch source code is available on GitHub, organised into git submodules. The most convenient way to work with it is via the superproject:

Note

If you are developing on a Windows machine, see Developing on Windows below for suggestions.

To start work on developing Pytch itself, clone this project, and run the top-level develop.sh script. This will first initialise and update the submodules’ content, and will appear to be doing nothing for a short while. You should then see messages indicating progress, finishing with a suggestion to run a dev-server.sh script.

You only need to run develop.sh once.

The dev-server.sh script should launch various webservers, and launch a browser running the webapp. This should support live reload, so if you make a small visible change to the UI, for example changing a button’s text, it should be reflected in the browser within a couple of seconds of saving the file from your editor/IDE.

To exit, type Ctrl-C repeatedly until you’re back at your shell prompt.

By default, the development webserver listens for connections from other machines on your local network. This can be useful in some settings, but in other settings you might prefer to only allow connections from your development machine. If so, you can launch the dev-server.sh script with the environment variable HOST set to localhost. This can be done with the shell command

HOST=localhost ./pytch-build/makesite/local-server/dev-server.sh

(assuming your shell is currently in the top-level pytch-releases directory).

Note

If you get an error duplicate session: pytchdev when trying to run the dev-server.sh script, this is probably because you closed the terminal window running a previous invocation of the dev-server.sh script without typing Ctrl-Cs. To fix the error, run tmux kill-session -t pytchdev and then run the dev-server.sh script again.

Developing on Linux

If, on Ubuntu, you encounter strange errors when trying to install nvm, check whether curl has been installed as a Snap. We have seen this lead to the situation where curl doesn’t have permission to write files. Installing curl via apt is recommended.

Developing on Windows

The preferred way to do development work on Pytch within Windows is to do so under the Windows Subsystem for Linux. Follow Microsoft’s instructions to set up what amounts to an Ubuntu virtual machine inside your Windows machine.

This sometimes involves a reboot.

(If you encounter an error like

Error: 0xc03a001a The requested operation could not be completed due to a virtual disk system limitation. Virtual hard disk files must be uncompressed and unencrypted and must not be sparse.

then this blog post describes how the author solved it.)

Once you have WSL set up, within your Ubuntu distribution run:

sudo apt update
sudo apt install zip unzip

(If the first of these commands gives errors involving

Temporary failure resolving archive.ubuntu.com

then one possible cause is that your WSL set-up does not have its DNS configured correctly. This StackExchange superuser post describes the process for using a public DNS server like Cloudflare’s 1.1.1.1, which might fix the problem.)

Then install nvm following the instructions in its README and install node v18 by running

nvm install v18

Once this is all done, you should be able to follow the main instructions above, starting with cloning the pytch-releases super-project.

If you would like to use Microsoft’s VSCode for development work, you can run your native Windows VSCode, and access your Ubuntu files using a Windows pathname starting \\wsl$\Ubuntu\home\your_username\.

Home directories

Be aware that your Windows home directory and your Ubuntu home directory are different. For example, when setting up SSH keys, you need to ensure you are working within your Ubuntu home directory. After launching WSL, you can use the shell command

cd

to change to your Ubuntu home directory.