synit-manual/src/install.md

# Source code, Building, and Installation

The initial application of Synit is to *mobile phones*.

As such, in addition to regular [system layer](./glossary.md#system-layer) concepts, Synit
supports concepts from mobile telephony: calls, SMSes, mobile data, headsets, speakerphone,
hotspots, battery levels and charging status, and so on.

Synit builds upon many existing technologies, but primarily relies on the following:

 - [PostmarketOS](https://postmarketos.org/). Synit builds on PostmarketOS, replacing only a
   few core packages. All of PostmarketOS and Alpine Linux are available underneath Synit.

 - [Preserves](https://preserves.gitlab.io/). The Preserves data language and its associated
   schema and query languages are central to Synit.

 - [Syndicate](https://syndicate-lang.org/). Syndicate is an umbrella project for tools and
   specifications related to the [Syndicated Actor Model](./glossary.md#syndicate-actor-model)
   (the SAM).

## You will need

 - A Linux development system. (I use Debian testing/unstable.)

 - Rust nightly and Cargo (perhaps installed via [rustup](https://rustup.rs/)).

 - Python 3.9 or greater

 - `git`, `ssh`, `rsync`

 - Make, a C compiler, and so on; standard Unix programming tools.

 - Source code for Synit components (see below).

 - A standard PostmarketOS distribution for the target computer or mobile phone. If you don't
   want to install on actual hardware, you can use a virtual machine. See the [instructions for
   installing PostmarketOS](https://wiki.postmarketos.org/wiki/Installation_guide).

 - **Great tolerance for the possibility of soft-bricking your phone.** This is experimental
   software! When it breaks, you'll often have to (at least) reinstall PostmarketOS from
   absolute scratch on the machine. I do lots of development using `qemu-amd64` for this
   reason.

## Get the code

The Synit codebase itself is contained in the [`syndicate-system` git
repository](https://git.syndicate-lang.org/synit/synit):

    git clone https://git.syndicate-lang.org/synit/synit

See the [README](https://git.syndicate-lang.org/synit/synit/src/branch/main/README.md) for an
overview of the contents of the repository.

Synit depends on published packages for Preserves and Syndicate support in each of the many
programming languages it uses. These will be automatically found and downloaded during the
Synit build process, but you can find details on the [Preserves](https://preserves.gitlab.io/)
and [Syndicate](https://syndicate-lang.org/) homepages, respectively.

## Build the packages

To build, type `make ARCH=`*\<architecture\>* in the root of your checkout, where
*\<architecture\>* is one of:

 - `aarch64` (default), for e.g. Pinephone or Samsung Galaxy S7 deployment
 - `x86_64`, for e.g. `qemu-amd64` deployment

The result of the build will be a collection of Alpine Linux `apk` packages in
`packaging/target/packages/`*\<architecture\>*`/`. At the time of writing, these include

 - `preserves-schemas`, common schema files for working with general Preserves data and schemas
 - `preserves-tools`, standard command-line tools for working with Preserves documents
   (pretty-printer, document query processor, etc.)
 - `py3-preserves`, python support libraries for Preserves
 - `py3-syndicate`, python support for the Syndicated Actor Model
 - `squeak-cog-vm` and `squeak-stack-vm`, Squeak Smalltalk virtual machine for the
   Smalltalk-based portions of the system
 - `syndicate-schemas`, common schema files for working with the Syndicated Actor Model
 - `syndicate-server`, package for the core system bus
 - `synit-config`, main package for Synit, with configuration files, `init` scripts, system
   daemons and so on.
 - `synit-pid1`, PID1 program for Synit that starts the core system bus and then becomes
   passive

## Install PostmarketOS on your system

Follow the instructions for your device on the [PostmarketOS
wiki](https://wiki.postmarketos.org/wiki/Devices).

Boot and connect your device to your development machine. Make sure you can `ssh` into it.

## Upload Synit packages

Use `scripts/upload-bundle.sh` to rsync the ingredients for transforming stock PostmarketOS to
Synit to the phone.

## Run the transformation script

Use `ssh` to log into your phone. Run `./transmogrify.sh`. (If your user's password on the
phone is anything other than `user`, you will have to run `SUDOPASS=yourpassword
./transmogrify.sh`.)

This will install the Synit packages. After this step is complete, the system will boot into
Synit; it may very well be unbootable, depending on the state of the codebase! Make sure you
know how to restore to a stock PostmarketOS installation.

## Reboot and hope

With luck, you'll see the Smalltalk user interface start up. From here, you can operate the
system normally, following the information in [the following chapter](./operation/index.md).