docs

BUILDING.md

@@ -0,0 +1,78 @@
+# 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`:
+
+```shell
+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:
+
+```shell
+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.**

README.md

@@ -0,0 +1,3 @@
+# PyBlocks - SPIKE Prime, but better
+
+PyBlocks is a patched version of `scratch-blocks` to add support for SPIKE Prime hardware. Block projects are transpiled into python and sent to PyBricks firmware on the hub, allowing for increased motor control and a generally better robot.