Tooling¶

Commands¶

The spp tool allows several commands to be run, to create, manage and run S++ projects. The commands are:

init: Create a new S++ project in the current folder. The project structure is created with the folders and main.spp file.
build: Compile the current project. The compiler will compile all .spp files in the src folder, and output the binary to the bin folder. All vcs/ext/ffi dependencies will be linked automatically.
run: Compile and run the current project. The steps are the same as build, but the binary is executed immediately after compilation.
clean: Clean the project. The folder containing the binary is emptied, and the project is ready to be built again. The binary folder is not deleted.
vcs: Install and update the vcs dependencies of the project. The compiler will check the vcs folder for newer versions of the dependencies, and will update them. Use fixed versions in the spp.toml file to prevent automatic updates.
version: Display the version of the S++ compiler that is currently installed. This can also be used to list versions of the vcs and ext dependencies.
help: Display the help message for the S++ compiler. This message contains a list of all commands, and a brief description of each command.

Project Initialization¶

The spp init command creates the folders and files in the current directory to create a new S++ project. This will enable the project to be built and run without structural errors. See the project structure section for more information on the folders and files created.

If the folder is not empty, a confirmation prompt will be shown. If there is a main.spp file in the current directory, and the overwrite prompt is confirmed, the main.spp file not be overwritten, as it assumed that a non-complete project is being converted into a valid S++ project.

No arguments can be passed to the init command. The spp.toml project configuration that is generated holds all the metadata that can be updated.

Project Building¶

The spp build command is used to compile the current project. It will recursively search the src folder for all .spp code files. The vcs and ext folders are then searched for code files too, and added to the module tree. Finally, the stub files inside the ffi modules are also linked, for symbol information.

Once all the code has been compiled into llvm code, the ffi libraries are linked into the binary, and the binary is output to the bin folder. The binary is placed in a subfolder of the build type (debug or release), and the dependencies are placed in the same folder.

If the project is already built, and only a subset of the files have been modified, then only those files are re-compiled. If part of the code changed is exportable (ie function signatures), then files that directly use these exported symbols are also recompiled. If only a function body is changed, then only that file is recompiled.

Each stage of the compiler can be parallelized, as the order of files does not matter. However, a stage of the compiler cannot begin until all modules have completed the previous stage. If a module contains an error, the build process stops, and the error is displayed.

Flag	Description
`--debug`	Compiles the project in debug mode (default).
`--release`	Compiles the project in release mode.
`--clean`	Cleans the project before building.
`--executable`	Compiles the project as an executable (default).
`--shared`	Compiles the project as a shared library.
`--static`	Compiles the project as a static library.

The default command is spp build --debug --executable --no-vcs-update.

Project Running¶

The spp run command can only be used if the --executable flag was used in the build step. It runs the built binary from the bin folder. The binary is recompiled if there are any changes to the code, and is run immediately after compilation. The build mode flag is required, to rebuild/run the correct binary.

Flag	Description
`--debug`	Compiles the project in debug mode (default).
`--release`	Compiles the project in release mode.
`--clean`	Cleans the project before building.

The default command is spp run --debug.

Project Cleaning¶

The spp clean command is used to delete the build mode folder if a flag is passed, or all build mode folders if no flag is passed. This will force the entire project to be re-built, as the binary is deleted. The bin folder is not deleted, as it is part of the project structure; only emptied.

Flag	Description
`--debug`	Cleans the debug build.
`--release`	Cleans the release build

Project VCS Updating¶

The spp vcs command is used to manage the vcs dependencies of the project. The compiler will check the vcs folder for all the dependencies. If the dependencies are not present, they will be cloned from the repository. If the dependencies are present, the compiler will try to git pull the repository to update the dependencies.

To prevent the automatic update of the dependencies, fixed versions can be specified in the spp.toml file. This will prevent the compiler from updating the dependencies, and will only use the specified version. The git pull command is skipped for fixed versions (matching a hash format).

The spp build command will run the spp vcs command every time. This is to ensure that the dependencies are up to date, and that the project is built with the latest code.

Compiler Version¶

The spp version command is used to display the version of the S++ compiler that is currently installed. This will output the version number, and nothing else. The --libraries flag can be used to list the versions of the vcs and ext libraries. This information is pulled from their respective spp.toml files, but is included as a convenience tool.

Flag	Description
`--libraries`	Lists the versions of the `vcs` and `ext` libraries.

Compiler Help¶

The spp help command is used to display a list of all commands and flags that can be passed to the commands.