pyblocks/BUILDING.md

Building PyBlocks

Compiling pyblocks is a multi-step process. There are generally two options for building any component of PyBlocks.

Because of the nature of how PyBlocks is compiled (via patching source code of various other projects), it is very easy to leave yourself in a broken state, unable to finish compilation. If you don't know what you're doing, use PBT.

You will need git, nodejs, npm, and python2 (under the command python2) installed.

Python 2 must be reachable at python2 - any other command will not work without further patching of the source tree.

Option 1: PBT (PyBlocks Build Tool) (Highly Recommended)

pbt.sh is a shell script designed to automate the process of developing PyBlocks. To use PBT, you need to be on a Unix (/-style paths, rougly POSIX compliant) system, with git, node, npm, and general baseutils available.

We highly recommend using PBT, as it makes it impossible to mess up the build process and leave you with a broken source tree.

Option 2: Manual (For experts only)

While pbt.sh is incredibly useful if you are on a Unix platform, it is still possible to compile PyBlocks on other platforms, you will simply need to follow the compilation instructions manually. Expect things to break permanently if you mess up, requiring you to delete your copy of PyBlocks and start over.

Step 1: Downloading sources

PyBlocks works by applying a set of patches (see patches/) to other projects' sourcecode. To do this, you'll need a local copy of their source trees. You have two options:

Option 1: PBT (Recommended)

Run ./pbt.sh clone. This will download a local copy of the required source code and place it where PBT expects them to be.

This may take a while, as the files being downloaded are fairly large. A relatively fast internet connection is required for this step.

Option 2: Manual

Step 1.1: Downloading scratch-blocks

Clone the scratch-blocks repository into scratch-blocks:

git clone https://github.com/scratchfoundation/scratch-blocks scratch-blocks

This may take a while, as the files being downloaded are fairly large. A relatively fast internet connection is required for this step.

Copy the patchbase for scratch-blocks from the file patches/blocks/PATCHBASE, then check it out with the following command:

cd scratch-blocks
git checkout [PATCHBASE GOES HERE]

Patching the source code

To compile PyBlocks, you need to apply a set of patches to the source code you just downloaded. This will convert that code into PyBlocks.

Option 1: PBT (Recommended)

Run ./pbt.sh patch to apply the patches. This can take a little while, as some of the patches are very large. If you interrupt this command, it is safe to run again.

Option 2: Manual

Apply all of the git patches in patches/ to their relative repositories:

• blocks goes to scratch-blocks

The way you do this depends on how your system is set up, but patches should be only applied with git apply.

Compiling scratch-blocks

Warning: This step can take a very long time (up to 10 minutes). Do not interrupt the build process. The scratch-blocks compiler has a bug in it that will lock up your computer if you interrupt this build process.

You only need to run this process once, when you compile scratch-blocks for the first time. Further edits to the source trees do not require this step to be repeated - you generally only need to run it the first time you build PyBlocks.

Option 1: PBT (Recommended)

Run ./pbt.sh compile to compile scratch-blocks. This will take a very long time. Do not interrupt this process.

Option 2: Manual

Run npm i in scratch-blocks/ to install dependencies and compile scratch-blocks. This will take a very long time. Do not interrupt this process.