This project is a lovechild of mine. So, if you want to contribute, I would be extremely greatful. :)
Contributing could mean a few different things:
- Reporting a bug
- Discussing the current state of the code
- Submitting a fix
- Adding to the official documentation
- Fixing my - possibly tons of - typos or grammar errors
- Proposing new features
- Becoming a maintainer
- Donations
In a few words: all contributions (even if they are just ideas or suggestions) are 100% welcome!
The project is mainly coded in Nim - it's a very powerful, compiled language that transpiles to pure C. So, we pretty-much get the good parts of C without the associated headaches. There is also a good deal of C/C++ (mainly for external libraries and wrappers).
Mainly, it consists of 8 parts:
- The parser, that takes some source/text and converts it into a list of Arturo values
- The evaluator, that takes a parse block (^) and converts into a list of bytecode's
- The execution method, that takes some evaluated bytecode and execute it one-by-one
- The helpers (generally, useful methods that are to be used in different parts of the codebase)
- The values (the very core of Arturo)
- The standard library, written mostly in Nim & Arturo
- The external libraries, mostly written in Nim & C/C++
- The main wrapper that brings it all together and orchestrates the whole action
To get an initial idea of the project, here's a brief guide to where is what:
| Location | Description |
|---|---|
bin/ |
The destination of the final binary after compilation |
examples/ |
A list of working examples in Arturo |
src/ |
The main source folder |
src/extras/ |
3rd party open-source code used by Arturo |
src/helpers/ |
Useful helper methods grouped by category and used mostly by library functions |
src/library/ |
The Arturo standard library functions, grouped by category |
src/system/ |
Components of the Arturo binary, written in Arturo (the REPL, the packager, etc) |
src/vm/ |
The Virtual Machine |
src/vm/bytecode.nim |
A list of all the VM bytecodes along with their description |
src/vm/env.nim |
VM Environment handling (paths, etc) |
src/vm/eval.nim |
The evaluator: where the parse tree turns into bytecode instructions |
src/vm/exec.nim |
The most important VM module, where the main loop is triggered |
src/vm/parse.nim |
The main lexer/parser: turning the initial input into a parse tree, of words, symbols and values |
src/vm/stack.nim |
Manipulation code for the different stacks used by the VM |
src/vm/value.nim |
The main Value object for our Virtual Machine along with numerous overloads, from initialization methods to printing and basic arithmetic |
src/arturo.nim |
The main entry; where all the magic begins |
tests/ |
Different unit tests |
tools/ |
Various tools, documentation generation, etc |
version/ |
Main version & build numbers |
The main compiler is implemented as a Bytecode interpreter / Stack-based VM and should run in most architectures.
The main goals are: expressiveness, brevity, performance and portability. (With that exact order)
The list of things to fix and/or add could be endless. But here is one, a bit prioritized (even though, inherently, incomplete and messy):
- Add support for big number handling (via GMP)
- Enrich the system library
- Add built-in support for Databases (Sqlite, etc)
- Implement HTML module
- Add more Server-related features
- Implement LaTeX generation module
- Add custom grammar parser functionality
- Optimize and refine the bytecode
- Improve VM performance
- Add the option of saving intermediate bytecode
- Add support for a package manager
- Add UI support (via libui? via webview? both?)
- Explore different uses of Arturo's dialecting capabilities (DSLs)
- Implement a basic Arturo compiler (written in Arturo 😊)
- Go full self-hosted (that's an ambitious one, I know...)
Anybody with an interest in programming languages, compiler design and/or some knowledge of Nim (it's not difficult to get an idea of what it is about once you see some code; trust me!) is more than welcome to contribute! So, how?
Let's have a look!
Before contributing to Arturo, you need to make sure you have all needed dependencies to compile it.
Our compiler is written in Nim, which depends on GCC.
Now, for the complete environment setup you may also have a look at the Github action: https://github.com/arturo-lang/setup-arturo/blob/main/action.yml - it's doing practically a complete setup with anything needed for each system.
Caution
Careful not to be confused with the fetch/compile mode: fetch just retrieves a prebuilt binary, so it just sets up the runtime environment, while compile - which is what you're interested in - sets up the environment for building Arturo too 😉
Important
Have in mind this is a quick guide based on Github Actions CI and this may require additional steps or less steps depending on your system. This setup is not intended for end-users, but for documenting steps for us, developers, and other contributors, so have it in mind before proceeding.
Install Nim
You need to install Nim in order to compile Arturo. The easiest way to install it is from the apt-get package manager.
apt-get install nimBut the recommended way is to use choosenim:
curl https://nim-lang.org/choosenim/init.sh -sSf | sh
choosenim 2.2.6Install dependencies
sudo apt-get update
sudo apt-get install libgtk-3-dev libmpfr-devNow, you need to add Webkit, but we have some little details to it.
If you're on Ubuntu 24.04 or greater, install:
sudo apt-get install -y libwebkit2gtk-4.1-devBut if you're on an older version:
sudo apt-get install -y libwebkit2gtk-4.0-devThis happens because 4.0 version of Webkit does not exist for newer versions of Ubuntu.
You need to install Nim in order to compile Arturo. The easiest way is install the latest version of clang, and then install nim from brew.
xcode-select --install
brew install nimBut you can also install nim from choosenim, which is the recommended way:
curl https://nim-lang.org/choosenim/init.sh -sSf | sh
choosenim 2.2.6Normally both work fine and are up-to-date
Installing Nim You need to install Nim in order to compile Arturo.
You may install it manually via the official installer. If you prefer, you can install from scoop or choco.
choco install nimor
scoop bucket add main
scoop install main/nimIf you're using scoop, choosenim won't be needed. Scoop already have version management built-in.
Installing MSYS2 and GCC
Nim depends on GCC and Arturo for Windows depends on some libraries for Mingw64.
In order to get this working, install MSYS2 from their official website.
Then open the Mingw64 instance and run:
pacman -S base-devel p7zip unzip mingw-w64-x86_64-toolchainIf you wish, you can also add Mingw64's bin to your PATH.
Search for "Environment Variables" and add <msys64's path>/mingw64/bin to your PATH.
Additional DLLs
Before compile, make sure you have all needed runtime dependencies at you bin folder.
cp src/extras/webview/deps/dlls/x64/webview.dll bin
cp src/extras/webview/deps/dlls/x64/WebView2Loader.dll bin
curl -L https://arturo-lang.s3.amazonaws.com/libgmp-10.dll -o bin/libgmp-10.dll
curl -L https://arturo-lang.s3.amazonaws.com/libmpfr-6.dll -o bin/libmpfr-6.dll
curl -L https://arturo-lang.s3.amazonaws.com/sqlite3_64.dll -o bin/sqlite3_64.dll
curl -L https://arturo-lang.s3.amazonaws.com/libgcc_s_seh-1.dll -o bin/libgcc_s_seh-1.dll
curl -L https://curl.se/ca/cacert.pem -o bin/cacert.pem
cp /mingw64/bin/libwinpthread-1.dll binInstall nim and its dependencies
For FreeBSD, We're installing Nim with pkg install nim. Which will probably fetch the previous Nim release, until all ports are updated, which AFAIK takes some time.
Would choosenim work? Perhaps, but haven't tested it.
pkg update
pkg install -y wget curl bash ca_root_nss jq
pkg install -y pkgconf openssl
pkg install -y nim gitInstall dependencies
pkg install -y gtk3 mpfr webkit2-gtk_41Pull requests are the best way to propose changes to the codebase and are actively encouraged:
- Fork the repo and create your branch from
master. - If you've added code that should be tested, add tests.
- If you've changed APIs, update the documentation.
- Ensure the test suite passes.
- Make sure your code lints.
- Issue that pull request!
In short: when you submit code changes, your submissions are understood to be under the same MIT License that covers the project. Feel free to contact the maintainers if that's a concern.
We use GitHub issues to track public bugs. Report a bug by opening a new issue; it's that easy!
It's the best way to easily help the project grow: the more issues to solve, the better it will become!
What we want in a great bug report:
- A quick summary and/or background
- Steps to reproduce
- Be specific!
- Give sample code if you can.
- What you expected would happen
- What actually happens
- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
People love thorough bug reports. I'm not even kidding.
Arturo's "official" documentation can be found here. This doesn't mean you cannot contribute - quite the opposite actually. Feel free to fix any error you spot, correct spelling/grammar mistakes (= non-native project creator disclaimer! lol), add examples or even write whole new sections.
So, where do we start?
The documentation can be divided into 2 parts:
- Library reference
- Miscellaneous pages
Every single one of Arturo's built-in functions resides in one of the modules in the src/library folder.
In each and every one of the files/modules, you can find a list of all the functions within that module.
One example would darken from the Colors module:
builtin "darken",
alias = unaliased,
rule = PrefixPrecedence,
description = "darken color by given percentage (0.0-1.0)",
args = {
"color" : {ValueKind.Color},
"percent" : {Floating}
},
attrs = NoAttrs,
returns = {ValueKind.Color},
example = """
darken #red 0.2 ; => #CC0000
darken #red 0.5 ; => #7F0000
darken #9944CC 0.3 ; => #6B308F
""":
##########################################################
if x.kind == Literal:
SetInPlace(newColor(alterColorValue(InPlace.l, y.f * (-1))))
else:
push newColor(alterColorValue(x.l, y.f * (-1)))As you can see, the code includes different pieces of data (description, args, example, etc) along with its implementation. This data is exactly what is is - automatically - included in Arturo's library reference (and the info function as well). Once you see a couple of them, it shouldn't be too difficult to figure out how it all works!
For all other pages in the official website (e.g. this one), all the content comes from templates that are then auto-magically (via Webize) converted to HTML.
So, if you want to edit one of these pages, just edit the corresponding template and your changes will be reflected at the very-next generation of the website (that part is up to me).
Here's where you can find all documentation template - all mostly written in a combination of Arturo itself and Markdown: Documentation
Given that Arturo is written and maintained by people for free, in their own free time, that also have their daily jobs, any donation would give the project the help it needs to get to the next level. And for that, we'd also need you help.
So...
We have different options for you:
You may also donate via Bitcoin:
