diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 0bbb333..4cb09cc 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -2,6 +2,26 @@ [Introduction](introduction.md) +# Tutorial +- [Installation](installation.md) + - [Prebuilt Binaries](prebuilt_binaries.md) + - [Build dependencies](build_dependencies.md) + - [Automated Build Script](automated_build_script.md) + - [Building Manually](building_manually.md) +- [Command Usage](command_usage.md) +- [Basics](basics.md) + - [Hello, World!](hello_world.md) + - [Variables](tutorial_variables.md) + - [Comments](tutorial_comments.md) + - [Values and Types](values_and_types.md) +- [Functions](functions.md) +- [Structures](structures.md) + +# Guidelines +- [Naming Conventions](naming_conventions.md) +- [Comment Conventions](comment_conventions.md) +- [Code Layout](code_layout.md) + # Specification - [Reserved Words](reserved_words.md) - [Comments](comments.md) @@ -12,3 +32,8 @@ - [Operators](operators.md) - [Function Definition](function_definition.md) - [Struct Definition](struct_definition.md) + +# Release History +- ["Vela" 0.x.x](vela.md) + - [0.1.0](vela_0.1.0.md) +- ["Fornax" 1.x.x](fornax.md) diff --git a/src/automated_build_script.md b/src/automated_build_script.md new file mode 100644 index 0000000..a60d6bb --- /dev/null +++ b/src/automated_build_script.md @@ -0,0 +1,30 @@ +# Automated Build Script + +This method requires the following installed: + +* uthash (in `/usr/include` or similar) +* A gcc-compatible C compiler linked to `cc` + * GCC and Clang are both tested and will yield similar results. +* Git (to get source code) +* Make (to organise building the code) + +Refer to [Build Dependencies](build_dependencies.md) for instructions on how to install dependencies. + +## Running the installer + +Run this command in your terminal: + +```sh +bash -c "$(curl -fsSL https://sols.dev/install.sh)" +``` + +This will: + +* Download a shell script from `https://sols.dev/install.sh` +* Run the contents of the shell script in the `bash` command interpreter + +The script does the following: + +* Checks if Ground and Solstice are installed on your system. +* If either Ground or Solstice aren't avaliable, it will download, build, and install the source code. +* If Ground or Solstice are installed, it will update them to the latest version. diff --git a/src/basics.md b/src/basics.md new file mode 100644 index 0000000..4d611a9 --- /dev/null +++ b/src/basics.md @@ -0,0 +1,3 @@ +# Basics + +This part of the tutorial shows you the basics of using Solstice. Click next to see the "Hello, World!" program! diff --git a/src/build_dependencies.md b/src/build_dependencies.md new file mode 100644 index 0000000..34e1e9f --- /dev/null +++ b/src/build_dependencies.md @@ -0,0 +1,25 @@ +# Build dependencies + +## macOS + +```sh +xcode-select --install +``` + +Then, download UTHash [here](https://github.com/troydhanson/uthash/archive/master.zip), and copy the contents of the `include` folder to `/usr/local/include`: + +```sh +sudo cp (/path/to/uthash-master)/include/* /usr/local/include +``` + +## Ubuntu/Debian + +```sh +sudo apt install gcc git make uthash-dev +``` + +## Arch Linux + +```sh +sudo pacman -S --needed gcc git make uthash +``` diff --git a/src/building_manually.md b/src/building_manually.md new file mode 100644 index 0000000..2c24460 --- /dev/null +++ b/src/building_manually.md @@ -0,0 +1,23 @@ +# Building Manually + +Refer to [Build Dependencies](build_dependencies.md) for instructions on how to install dependencies. + +Build and install Ground: + +```sh +git clone https://chookspace.com/ground/ground +cd ground +make +sudo make install +cd .. +``` + +After this, build and install Solstice: + +```sh +git clone https://chookspace.com/solstice/solstice +cd solstice +make +sudo make install +cd .. +``` diff --git a/src/code_layout.md b/src/code_layout.md new file mode 100644 index 0000000..a71cfce --- /dev/null +++ b/src/code_layout.md @@ -0,0 +1 @@ +# Code Layout diff --git a/src/command_usage.md b/src/command_usage.md new file mode 100644 index 0000000..2696a8d --- /dev/null +++ b/src/command_usage.md @@ -0,0 +1,51 @@ +# Command Usage + +``` +Solstice programming language +Usage: solstice [-h] [--help] [-p] [--print] [-b ] [--bytecode ] [-c ] [--compile ] +Args: + : Solstice source file + -h or --help: Prints this help message and exits + -p or --print: Prints textual version of Ground bytecode to console + -b or --bytecode : Generates Ground bytecode (.grbc) and saves it to the provided filename + -c or --compile : Compiles Ground to Linux x86_64 assembly, outputs a binary to the provided filename (experimental) + If no extra arguments are provided, the generated Ground bytecode will be executed. +``` + +## Arguments: + +### `` + +The Solstice source file to run. + +There should never be more than one file, as Solstice allows files to import each other, rather than compiling multiple files into one manually. + +### `-h` or `--help` + +Shows the help message above. + +### `-p` or `--print` + +Prints the textual version of the generated Ground bytecode to the console. + +This is useful for debugging the compiler, and ensuring the correct output is produced for the GroundVM. + +### `-b ` or `--bytecode ` + +Outputs Ground bytecode (in `grbc` format) and saves it in the file ``. + +Ground bytecode is useful for distributing software in a format where the target machine does not need Solstice installed, only the Ground VM. + +Run the compiled bytecode with: + +```sh +ground -b +``` + +### `-c ` or `--compile ` + +Compiles the Ground bytecode to assembly using the [Tram](https://chookspace.com/tram/tram) backend, outputting a binary named ``. + +Requires Ground to be built with Tram support, and Tram to be installed on your system. + +This backend is experimental and does not support all features. diff --git a/src/comment_conventions.md b/src/comment_conventions.md new file mode 100644 index 0000000..8d9014b --- /dev/null +++ b/src/comment_conventions.md @@ -0,0 +1 @@ +# Comment Conventions diff --git a/src/fornax.md b/src/fornax.md new file mode 100644 index 0000000..aade0b4 --- /dev/null +++ b/src/fornax.md @@ -0,0 +1,12 @@ +# "Fornax" 1.x.x + +Fornax will be the codename for the 1.x.x releases of Solstice. It is named after the [Fornax constellation](https://en.wikipedia.org/wiki/Fornax). + +## Release Target + +Fornax will release when: + +* The compiler core is stable enough to host moderately sized projects +* The standard library is capable enough for many programming projects + +Fornax is not currently released. diff --git a/src/functions.md b/src/functions.md new file mode 100644 index 0000000..0c5faf5 --- /dev/null +++ b/src/functions.md @@ -0,0 +1 @@ +# Functions diff --git a/src/hello_world.md b/src/hello_world.md new file mode 100644 index 0000000..0f2c710 --- /dev/null +++ b/src/hello_world.md @@ -0,0 +1,22 @@ +# Hello, World! + +Create a new file on your computer (preferably in a new folder) named `main.sols`. In the file, write the following: + +```solstice +puts "Hello, World!" +``` + +Save the file, then run in your terminal: + +```sh +solstice main.sols +``` + +Solstice will run the file for you, which should print `Hello, World!` to the console. + +Here's what it does: + +* `puts`: Stands for "put something". It's Solstice's built in "please print out this thing's current state" operator. +* `"Hello, World!"`: A string. A string is a collection of characters. In Solstice, you denote a string by surrounding your text with double quotes (`"`). + +Next up: using variables! diff --git a/src/installation.md b/src/installation.md new file mode 100644 index 0000000..5a0298e --- /dev/null +++ b/src/installation.md @@ -0,0 +1,11 @@ +# Installation + +Solstice is fully supported and tested on Linux, however should work on most UNIX-like environments. Windows support is theoretically possible, however not all features are avaliable, so use WSL, MSys, or Cygwin instead. + +## Which method is for you? + +Use a [prebuilt binary](prebuilt_binaries.md) if you're in a rush, or you can't get a compiler on your system. + +Use the [automated build script](automated_build_script.md) for a full install of Solstice and Ground, with maximum flexibility. + +Do a [manual build](building_manually.md) if you intend to contribute to the Solstice source code. diff --git a/src/introduction.md b/src/introduction.md index f837315..f2691d3 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -1,5 +1,7 @@ # Introduction -Welcome to the Solstice docs! For now, the documentation is in the format of a specification, which instructs you on how Solstice should behave. In future, a tutorial (similar to the Rust book) will be written which shows you each part of the language, instead of declaring it like the spec. +Welcome to the Solstice documentation! Here we have a tutorial (starting [here](installation.md)) and a specification for the Solstice programming language. + +If you're new to Solstice, I'd recommend starting the tutorial, at the [installation](installation.md) page. If you've already installed Solstice, start at the [Basics](basics.md) page. Docs generated by mdBook. diff --git a/src/naming_conventions.md b/src/naming_conventions.md new file mode 100644 index 0000000..d2de377 --- /dev/null +++ b/src/naming_conventions.md @@ -0,0 +1 @@ +# Naming Conventions diff --git a/src/operators.md b/src/operators.md index 68d6ddd..0c2ecc7 100644 --- a/src/operators.md +++ b/src/operators.md @@ -121,3 +121,25 @@ puts x so the type checker can know what `x` is. +## `use` + +The `use` operator lets you import code from libraries, either from in the local folder or installed in the `$SOLSTICE_LIBS` directory, which defaults to `/usr/lib/solstice`. + +When using `use`, Solstice will insert the selected file's contents at that position. + +### Local `use` + +Supply a string after `use` which is the path to the file to import, without the `.sols` extension. + +```solstice +use "parser/Node" +use "parser/parser" +``` + +### Global `use` + +Supply an identifier after `use` which is the name of the library to import, without the `.sols` extension. + +```solstice +use io +``` diff --git a/src/prebuilt_binaries.md b/src/prebuilt_binaries.md new file mode 100644 index 0000000..ba61fb0 --- /dev/null +++ b/src/prebuilt_binaries.md @@ -0,0 +1,11 @@ +# Prebuilt Binaries + +Solstice binaries statically linked with Ground are avaliable from the [Solstice releases page](https://chookspace.com/solstice/solstice/releases). For now, these are only for Linux x86_64, but more options may be avaliable in future. + +Download the latest release, copy it into a folder in your path (such as `/usr/local/bin`) and enjoy! + +## Producing release binaries + +There is a script [on Chookspace](https://chookspace.com/solstice/builder) which builds Solstice and Ground in a container. Use this script for building production releases, and determining whether bugs are setup-specific or affect all people. + +Use this script to produce prebuilt binaries for the releases page. diff --git a/src/structures.md b/src/structures.md new file mode 100644 index 0000000..9852861 --- /dev/null +++ b/src/structures.md @@ -0,0 +1 @@ +# Structures diff --git a/src/tutorial_comments.md b/src/tutorial_comments.md new file mode 100644 index 0000000..56accd1 --- /dev/null +++ b/src/tutorial_comments.md @@ -0,0 +1,37 @@ +# Comments + +In Solstice, there are 3 ways to do comments: + +## `//` (Single-Line Comment) + +Writing `//` tells Solstice to ignore the rest of the line. + +Some examples: + +```solstice +puts 2 + 2 // should be 4 + +// This variable holds the status code from checkStatus() +statusCode = checkStatus("file.txt") +``` + +This comment should be used when writing your code's logic in Solstice. + +## `/* */` (Multiline Comment) + +Any text in between `/*` and `*/` will be ignored. These comments should be used to document functions and structs (we'll get to those later.) + +Example: + +```solstice +/* + Adds two numbers together. +*/ +def add(int a, int b) int { + return a + b +} +``` + +## `#` (Shebang Comment) + +Use this comment only for using Solstice as a script interpreter in a shebang. Effectively the same as `//`, but we recommend using `//` over `#`. diff --git a/src/tutorial_variables.md b/src/tutorial_variables.md new file mode 100644 index 0000000..5179761 --- /dev/null +++ b/src/tutorial_variables.md @@ -0,0 +1,32 @@ +# Variables + +## Creating Variables + +In Solstice, you can initialize a variable using the syntax: + +```solstice +name = value +``` + +where: + +* `name` is the name of your variable. You can use all letters in variable names, as well as underscores and numbers. + * The standard way to name your variables in Solstice is with `camelCase`. +* `value` is some sort of value. This value can be: + * an integer (number with no decimal place) + * a double (number with a decimal place) + * a string (collection of characters, as seen before) + * a character (a single letter) + * a boolean (either `true` or `false`) + +We'll look at types of values in the next part. + +## Recalling Variables + +Recall a variable's content by using it's name: + +```solstice +puts name +``` + +where `name` is the name of your variable. diff --git a/src/values_and_types.md b/src/values_and_types.md new file mode 100644 index 0000000..ed8522a --- /dev/null +++ b/src/values_and_types.md @@ -0,0 +1,72 @@ +# Values and Types + +In Solstice, everything is a value, and every value has a type. Values can be moved around and passed to different functions, however to pass them around their type must be confirmed. + +## `int` + +An `int` is a signed (meaning either positive or negative) 8-byte integer (meaning no decimal place). + +Using this size, Solstice can accurately process numbers between `-9,223,372,036,854,775,807` and `9,223,372,036,854,775,807`. + +Integers are represented as a collection of digits not seperated by anything, such as: + +```solstice +123 +7483 +423843269 +``` + +## `double` + +A `double` is a signed 8-byte floating-point (meaning with a decimal place) number. + +Using this size, Solstice can accurately process numbers between 15 and 17 digits long. + +Doubles are represented as a collection of digits, with a dot (`.`) seperating the ones and tenths positions, such as: + +```solstice +3.14 +432.543 +5907432.432 +``` + +## `string` + +A `string` is a collection of characters which end with a null byte (handled by Solstice). + +Solstice can accurately process strings of any size, provided your computer has enough memory. + +Strings are represented as a collection of characters surrounded by double quotes (`""`), such as: + +```solstice +"Hello, World!" +"Solstice is cool" +"Rust kinda mid" +``` + +## `char` + +A `char` is a signed 1-byte integer, represented as an ASCII character, however can also be used to represent a single byte in a stream. + +Solstice can accurately process any ASCII character. + +Characters are represented as a single character surrounded by single quotes (`''`), such as: + +```solstice +'a' +'b' +'c' +``` + +## `bool` + +A `bool` is a variable which can either be `true` or `false`. + +```solstice +true +false +``` + +## Other Types + +Solstice has three other types: `fun`, `template`, and `object`, but we'll cover these in the [Functions](functions.md) and [Structures](structures.md) pages. diff --git a/src/vela.md b/src/vela.md new file mode 100644 index 0000000..2e634e7 --- /dev/null +++ b/src/vela.md @@ -0,0 +1,26 @@ +# "Vela" 0.x.x + +Vela is the codename for the 0.x.x releases of Solstice. It is named after the [Vela constellation](https://en.wikipedia.org/wiki/Vela_(constellation)). + +## Changes + +Vela is the prerelease version of Solstice, and is the phase where core compiler features are added. Here are some features added in Vela to the compiler: + +* `puts` +* Variables +* Values +* Static type system +* `if`, `while` control flow +* Functions + * Lambda/Anonymous Functions + * Named Functions + * Closures attached to functions +* Structs + * Fields + * Methods + * `private` and `protected` + * `as`-methods + * Constructors, destructors, duplicators +* Generics (in progress) +* `pragma` directives (in progress) +* Libraries with `use` diff --git a/src/vela_0.1.0.md b/src/vela_0.1.0.md new file mode 100644 index 0000000..8316ced --- /dev/null +++ b/src/vela_0.1.0.md @@ -0,0 +1,24 @@ +# "Vela" 0.1.0 + +This is the very first release of Solstice! Not much to see here. + +This release contains: + +* `puts` +* Variables +* Values +* Static type system +* `if`, `while` control flow +* Functions + * Lambda/Anonymous Functions + * Named Functions + * Closures attached to functions +* Structs + * Fields + * Methods + * `private` and `protected` + * `as`-methods + * Constructors, destructors, duplicators +* Generics (partially, there are many bugs) +* `pragma` directives in the parser +* Libraries with `use`