Learn the basics of Vanadin step-by-step

Installation of Vanadin

To install Vanadin, you have two options:

Install Vanadin via Cargo
Install Vanadin manually

Installing Vanadin via Cargo

If you do not have cargo, you can install it by following the Official Installation Guide of Rust & Cargo

After you installed Cargo, run cargo install vanadin to install Vanadin.

To validate the installation, you can run vanadin info and you should see something like this:

[INFO] Running Vanadin v0.1.0
[INFO] Blazingly fast building and testing framework.
[INFO] Made by DraftedDev

Installing Vanadin manually

W.I.P

Your First Project

Initializing Vanadin

To get started, you first need to create a basic .vanadin folder.

To do so, run:

$ vanadin init

Anatomy of your `.vanadin`

The .vanadin folder is where you define tasks, set environment variables and configure your project.

It should look this:

My Project
├── .vanadin
│   ├── Vanadin.toml
│   └── tasks
│       └── build.js
└── ...

The `Vanadin.toml` file

The Vanadin.toml file defines the tasks, environment variables and other stuff for Vanadin.

Tasks are defined like this:

[task.task-name]
name = "task-name" # The name of the task. Defaults to the name of the [task.<name>] section
about = "About the task aka the its description" # Defaults to an empty string.
src = "./tasks/my-task.js" # This defaults to './tasks/<task-name>.js' if not specified

The `tasks` folder

This is the default location of all tasks.

You should define tasks in this folder, but if you want to define them elsewhere, make sure to set the src field in your [task] section.

Environment variables

Environment variables are set in the [env] section of your Vanadin.toml file:

[env]
MY_VARIABLE = "my-value"
SECRET_NUMBER = "123"

These variables are set before the execution of a task, so you can use them in the task.

Running tasks

To run a task, execute:

$ vanadin x -t your-task-name

When creating your .vanadin with vanadin init, you can run the generated build task via vanadin x -t build.

Pre- and Post-Tasks

You can define pre- and post-tasks to execute before and after the main task.

These tasks can be defined in the [task] section like this:

[task.prepare]
about = "Prepare your meal"

[task.eat]
about = "Eat your meal"
pre = ["prepare"]
post = ["cleanup"]

[task.cleanup]
about = "Clean up after your meal"

When running the eat task, the prepare and cleanup tasks will be executed before and afterward.

NOTE 1: The pre and post tasks will be executed in the order they are defined.

NOTE 2: Make sure that pre- and post-tasks do not depend on each other, so that infinite loops may occur.

Learn how to code your first script via JS and pre-defined modules.

Coding in JavaScript

You may have noticed, that all tasks end with .js. This is because all tasks are written in plain old, easy & fast JavaScript.

Vanadin uses the QuickJS Engine under the hood to execute fast and tiny JavaScript code with a tiny runtime and small footprint.

The engine supports most of the ES2023 specification. Due to most tasks not requiring advanced features, Vanadin only supports most basic JavaScript with BaseObject support.

It should also be kept in mind, that scripts are executed in non-global scope and are not strict by default.

Built-in Features

Vanadin provides a set of useful features by default.

Following functions may be called without extra module imports:

print("Some String"); // prints "Some String"
println("Another String"); // prints "Another String" with a newline at the end
assert(condition); // tests if condition is true and throws an error otherwise
throw("Error Message"); // throws an error with the given message

There are also pre-defined constants:

println(ID); // Prints the ID/name of the current task
println(ABOUT); // Prints the description of the current task

Tools & "Runners"

Vanadin contains some special modules for integration with compilers, frameworks and more.

You can import different modules from tools/...:

import { run } from "tools/node";

// runs `node index.js`
run("index.js");

The `tools/node` Module

The tools/node module provides useful functions for working with Node.js.

Import it with:

import { run, ... } from "tools/node";

Functions

`run(file)`

Runs the given file in Node.js with extra development features. Basically just runs node <file>. Returns the exit or null if there was no exit code.

`node(cmd)`

Runs the given command in Node.js. Basically just runs node <cmd>. Returns the exit or null if there was no exit code.

`launch(file)`

Runs the given file in Node.js without extra development features. Basically just runs node <file>. Returns the exit or null if there was no exit code.

The `tools/python` Module

The tools/python module provides useful functions for working with Python.

Import it with:

import { run, ... } from "tools/python";

Functions

`run(file)`

Runs the given file or __main__.py if null is given. Executes the file with extra development features and returns the exit code or null if none was provided.

`py(cmd)`

Runs the given command using the python command. Returns the exit code or null if none was provided.

`launch(file)`

Runs the given file or __main__.py if null is given. Executes the file with extra optimization and returns the exit code or null if none was provided.

The `tools/cargo` Module

The tools/cargo module provides useful functions for working with Rust & Cargo.

Import it with:

import { run, ... } from "tools/cargo";

Functions

`cargo(cmd)`

Runs the given command and returns the exit code if given, otherwise null.

`run()`

Executes cargo run and returns the exit code if given, otherwise null.

`build()`

Executes cargo build and returns the exit code if given, otherwise null.

`test(test)`

Executes cargo test --test <test> or cargo test if no test is given and returns the exit code if there is one, otherwise null.

`clean()`

Executes cargo clean and returns the exit code if given, otherwise null.

`release()`

Builds the crate in release mode with --config strip=true --future-incompat-report and returns the exit code if given, otherwise null.

`env` Module

The env module provides access to environment variables and basic process variables.

To import the env module, use the import keyword:

import { get, set, ... } from 'env';

Functions

`get(key)`

Returns the value of the environment variable with the name key.

`set(key, value)`

Sets the value of the environment variable with the name key to value.

`remove(key)`

Removes the environment variable with the name key.

`dir()`

Returns the current working directory.

`os()`

Returns the operating system name.

`arch()`

Returns the architecture.

`family()`

Returns the operating system family.

`process` Module

The process module provides useful functions for spawning processes, running commands and more.

To import the process module, use the import keyword:

import { cmd, ... } from 'process';

Functions

`cmd(command, args)`

Runs the given command with the given arguments and returns the exit code. Returns null if an error occurs.

`exit(code)`

Exits the process with the given exit code.

`id()`

Returns the current process ID.

`fs` Module

The fs module provides functions for interacting with the file system.

To import the fs module, use the import keyword:

import { readFile, ... } from 'fs';

Functions

`readFile(file)`

Returns the contents of the given file as a string or null if an error occurs.

`writeFile(file, content)`

Writes the given content to the given file.

`readFileBytes(file)`

Returns the contents of the given file as a byte array or null if an error occurs.

`writeFileBytes(file, content)`

Writes the given content to the given file as a byte array.

`createFile(file)`

Creates a new file with the given name.

`removeFile(file)`

Deletes the given file.

`createDir(dir)`

Creates a new directory with the given name.

`removeDir(dir)`

Deletes the given directory.

`exists(file)`

Checks if the given file exists.

`log` Module

The log module provides functions to use the built-in Vanadin logger.

To import the log module, use the import keyword:

import { info, ... } from 'log';

Functions

`info(msg)`

Logs an informational message.

`warn(msg)`

Logs a warning message.

`error(msg)`

Logs an error message.

`debug(msg)`

Logs a debug message.

`trace(msg)`

Logs a trace message.

`math` Module

The math module provides functions to use the built-in Vanadin logger.

To import the math module, use the import keyword:

import { sqrt, ... } from 'math';

Functions

`sqrt(x)`

Returns the square root of x.

`pow(base, exp)`

Returns the value of base raised to the power of exp.

`sin(x)`

Returns the sine of x.

`cos(x)`

Returns the cosine of x.

`tan(x)`

Returns the tangent of x.

`asin(x)`

Returns the arc sine of x.

`acos(x)`

Returns the arc cosine of x.

`atan(x)`

Returns the arc tangent of x.

`sinh(x)`

Returns the hyperbolic sine of x.

`cosh(x)`

Returns the hyperbolic cosine of x.

`tanh(x)`

Returns the hyperbolic tangent of x.

`asinh(x)`

Returns the inverse hyperbolic sine of x.

`acosh(x)`

Returns the inverse hyperbolic cosine of x.

`atanh(x)`

Returns the inverse hyperbolic tangent of x.

`exp(x)`

Returns the exponential of x.

`log(x, base)`

Returns the logarithm of x with the given base.

`log2(x)`

Returns the base-2 logarithm of x.

`log10(x)`

Returns the base-10 logarithm of x.

`floor(x)`

Returns the largest integer less than or equal to x.

`ceil(x)`

Returns the smallest integer greater than or equal to x.

`round(x)`

Returns the value of x rounded to the nearest integer.

Constants

`E`

Euler's number e

`PI`

Archimedes' constant π

`sys` Module

The sys module provides functions to retrieve system information.

To import the sys module, use the import keyword:

import { cpuCount, ... } from 'sys';

Functions

NOTE: Most or all of these functions are quite expensive, since they request system information from the OS and are not cached.

`cpuCount()`

Returns the number of CPUs in the system or null if it cannot be determined.

`cpuBrands()`

Returns an array of CPU brands in the system.

`cpuNames()`

Returns an array of CPU names in the system.

`cpuFrequencies()`

Returns an array of CPU frequencies in the system.

`cpuUsages()`

Returns an array of CPU usage in the system.

`availableMemory()`

Returns the available memory in the system.

Generally, free memory refers to unallocated memory whereas available memory refers to memory that is available for (re)use.

`freeMemory()`

Returns the free memory in the system.

Free memory refers to unallocated memory whereas available memory refers to memory that is available for (re)use.

Windows doesn't report free memory so this method returns the same value as availableMemory().

`totalMemory()`

Returns the total memory in the system.

`usedMemory()`

Returns the used memory in the system.

`http` Module

The http module provides functions to work with the HyperText Transfer Protocol (HTTP).

To import the http module, use the import keyword:

import { serve, ... } from 'http';

Functions

`serve({}, func)`

Starts an HTTP server with the given function to handle requests and an optional configuration object.

The default config looks like this:

{
    address: 'http://127.0.0.1:8080',
    log: true
}

The func function only takes one argument: the req object.

This object looks like this:

{
    url: 'http://127.0.0.1:8080/',
    method: 'GET',
    headers: [] // list of headers
}

You can also close this server by going to <server-address>/close-vanadin-server where <server-address> is the address of the server.

Official Vanadin Book