Newspeak is a live object-capability language in the Smalltalk tradition
# 1. Newspeak
[Newspeak](http://www.newspeaklanguage.org/) is a new programming language in the tradition of Self and Smalltalk.
The Newspeak IDE is delivered via the web at [https://www.newspeaklanguage.org/webIDE/](http://www.newspeaklanguage.org/webIDE/) as a Progressive Web App (PWA).
This means that you can install it locally on your device, and then run it
without needing an internet connection. Updates are delivered
automatically whenever you are online - this is enabled by the PWA.
If you are testing or developing in Newspeak, the online version is all you need.
You could stop here and consult the Newspeak resources linked above.
But you may decide to build and serve Newspeak or your own Newspeak application locally.
The sections explain how to do so.
Note: below, the terms 'serve', 'server' refer to
'serve in a HTTP server', 'HTTP server' or similar.
# 2. How to build, deploy, and serve Newspeak applications
This is only a terse introduction to creating and serving Newspeak applications.
A Newspeak application is a Newspeak object which adheres to a few
specific API naming conventions. Its class can be saved to a `.ns`
source file, and used to create an instance that is serialized into a
binary `.vfuel`, which is deployed and served.
> [!NOTE]
> You can usually run the application inside the IDE for
> purposes of testing and development, provided you have the source
> code loaded in the IDE. We won't discuss that here - this document
> is focused on application deployment.
A `.vfuel` file can be created from its source class in one of two ways:
1. From the locally served or online [Newspeak IDE](http://www.newspeaklanguage.org/webIDE) by clicking the **[deploy]** link beside the application class. This process is not described in this document.
2. From a command line, by first saving the application class to a `.ns` source file, then running the `build.sh` script described below. To use this command line method, you need to install several items. This process is described in the [Building Newspeak from scratch](#3-building-newspeak-from-scratch) section and its subsections.
To serve a Newspeak application in a HTTP server, you need a binary file with `.vfuel` extension, one or more HTML files, and at least two files, 'primordialsoup.js' and 'primordialsoup.wasm' (both created by `build.sh`), and potentially other application specific resources.
# 3. Building Newspeak from scratch
TL;DR: If you want to build the Newspeak IDE or any Newspeak
application from scratch, follow the installation steps in section 3.1
and subsection 3.1.1 (each only needs to be performed once). Then
follow the steps in section 4.1 (for the Newspeak IDE running as a
PWA) or 4.2 (for any application, running as a website). The steps in section 4.1 or 4.2 are repeated after any change in the application.
In addition to using the online version of the [Newspeak IDE](http://www.newspeaklanguage.org/webIDE/), you can build, deploy, and serve the Newspeak system, or any Newspeak application, on your computer. There may be a few reasons to build and use the Newspeak system this way:
- You just want to learn how to do it.
- You want to write, build, and serve your own Newspeak application (a `.vfuel` file), or serve the Newspeak IDE from your own HTTP server for local or public consumption.
Read and follow the steps below to build Newspeak locally (on your computer) from scratch.
## 3.1 Building Newspeak: installing required software
This is needed one-time only.
Building Newspeak locally requires some software to be downloaded,
cloned from Github, or installed: *Newspeak*, *Primordialsoup* and
its dependencies and targets: *Emscripten*, *Scons*, and *g++-multilib*. Details of how to install the required software are below.
The default directories for installing *Newspeak*, *Primordialsoup* and *Emscripten* are determined by environment variables set in `newspeak/tool/newspeak_env.sh`. These variables and their default values are
```sh
export EMSDK=~/software/emsdk # Emscripten directory
export NEWSPEAK=~/software/nswasm/newspeak # Newspeak directory
export PRIMORDIALSOUP=~/software/nswasm/primordialsoup # Primordialsoup directory
```
We use these defaults throughout the rest of this document. If you wish to use different directories, you will need to do two things:
- Adjust references to the above directory names in this document
- After cloning Newspeak in the steps below, edit the file `newspeak/tool/newspeak_env.sh` and adjust the directory names to your situation.
The installation steps:
1. Start with creating a directory for Newspeak and Primordialsoup, `~/software/nswasm` and then clone this repo under it.
2. In `~/software/nswasm`, also clone <https://github.com/newspeaklanguage/primordialsoup> and switch to the branch called `extraRevs`.
You can use the following commands to execute 1. and 2. just above:
```sh
mkdir -p ~/software/nswasm
cd ~/software/nswasm # Adjust to your directory path
git clone https://github.com/newspeaklanguage/newspeak.git
git clone https://github.com/newspeaklanguage/primordialsoup.git
cd primordialsoup
git checkout extraRevs
```
To be clear: at this point, you should now have a directory named `~/software/nswasm`, with two
subdirectories; `newspeak`, containing this repository, and `primordialsoup`, containing the `extraRevs` branch of <https://github.com/newspeaklanguage/primordialsoup>.
> [!IMPORTANT]
> If you are using 'non default' directories for your installation, now edit the file `newspeak/tool/newspeak_env.sh`, change the exported variables there, and save the file.
### 3.1.1 Building Newspeak: installing Primordialsoup dependencies
Next, you will need to install software needed by the Primordialsoup build.
Unless you are targetting Fuchsia, follow steps 1 to 3 in this section to install and build Primordialsoup and its dependencies.
1. **Install and configure Emscripten and Primordialsoup dependencies:** building Primordial Soup requires a C++ compiler and SCons.
- On Debian/Ubuntu:
```sh
sudo apt-get install g++-multilib scons
```
- On Opensuse:
```sh
sudo zypper install scons
sudo zypper install -t pattern devel_basis devel_C_C++ 32bit
```
- On macOS, install XCode and SCons.
- On Windows, install Visual Studio and SCons.
2. **Install and configure the Emscripten SDK (`emsdk`):** Emscripten
is a compiler that compiles C and C++ sources to WebAssembly, which
can then be executed by browsers.
Clone the Emscripten SDK (`emsdk`) using these steps
```sh
# Clone the emsdk repository
cd ~/software/nswasm
git clone https://github.com/emscripten-core/emsdk.git
# Install the emsdk version 4.0.11
cd emsdk
./emsdk install 4.0.11
./emsdk activate 4.0.11
. ./emsdk_env.sh
# List the emsdk installed
./emsdk list
```
3. **Build Primordialsoup (optional):** You can now build primordialsoup to make sure everything installed. This step is not necessary as Primordialsoup build is part of the Newspeak build in the next section - but running it should catch any dependencies issues early.
```sh
cd ~/software/nswasm/primordialsoup # Adjust to your directory path
. ../newspeak/tool/newspeak_env.sh # Set EMSDK var for next line
. $EMSDK/emsdk_env.sh # Setup emsdk's environment
./build os=emscripten arch=wasm # Build wasm using emscripten
```
There should be no errors in the last step, and you should see directories in the `out` directory under `primordialsoup`, notably there should be files `primordialsoup/out/ReleaseEmscriptenWASM/{primordialsoup.html,primordialsoup.js,primordialsoup.wasm}` and `primordialsoup/out/snapshots/WebCompiler.vfuel` which are used in the Newspeak build. If there are errors, you may be missing some `primordialsoup` dependencies described in the section above.
Note: For original instructions of Primordialsoup dependencies that include Fuchsia as a target, follow the instructions at <https://github.com/newspeaklanguage/primordialsoup/blob/master/docs/building.md>.
## 3.2 Building and deploying Newspeak applications: lifecycle
The above section [Building Newspeak: installing required software](#3.1-building-newspeak:-installing-required-software) including its subsection [Building Newspeak: installing Primordialsoup dependencies](#3.1.1-building-newspeak:-installing-primordialsoup-dependencies) **only needs to be performed once during installation**.
This section and sections below describe the repeated 'build', 'deploy', 'serve' lifecycle of Newspeak applications.
> [!IMPORTANT]
> All scripts to build and deploy a Newspeak application are in the `newspeak/tool` directory, and must be executed from the `newspeak/tool` directory. The Newspeak IDE is only one possible Newspeak application.
The term **build** refers to the process which creates the `.vfuel`
binary files from the application source `.ns` files. The script
`newspeak/tool/build.sh` is the build script. You need to run a 'build' to regenerate the application's `.vfuel`
file.
Before creating a `.vfuel`, you should ensure that you have
saved any modified source code it depends upon, be it one of the Newspeak core classes, or a class that is a part of your application.
The term **deploy** refers to the process of copying the Newspeak application `.vfuel` file and other files and resources (`.html`, `.js`, `.png`) to the 'deploy directory' where an HTTP server is or will be running. The 'deploy' step also copies scripts that can start an HTTP server to the 'deploy directory'. Newspeak applications can be deployed in two ways: as a regular website or as a Progressive Web App (PWA).
- *Deploying as a website*: is performed by the script `deploy-all-vfuels-as-website.sh`. Running this script deploys all `.vfuel` files b