Modules

If you are writing a program that has more than one file, a module is probably the best way to organize it. Modules have the benefit that you can easily compile your complex program with one command vsl .. VSL modules allow have the benefit of automated built-steps, file resolution, cleanup, installation, module management, and more.

The basic module

A VSL module is just a directory with a module.yml. The module.yml specifies that a directory is a VSL module. This specifies the module name, description, source files, target, and more. Here's an example module.yml for a simple Greeter program:

name: Greeter
description: Reads user name from STDIN and greets them.

version: 1.0.0

sources:
  - src/*.vsl

This will search the src/ directory and compile all immediate files ending in .vsl

Project Structure

VSL is pretty flexible with however you want to structure your project but this is recommended format:

./
 |- module.yml
 |- src/
 |   |- source.vsl
 |- modules/
 |   |- module1/

where src/ contains the all the sources. If you use subdirectories in src/. Use sources: - src/**/*.vsl in your module.yml.

The directory modules probably doesn't need to exist for basic programs but if you have modules you would like to use, place it in this directory. It is recommended to use git submodules for these directories. This directory will automatically created with the vsl install command.

Module Lookup

So when you do import my-module. That module comes from two default locations:

• $(vsl --prefix)/libraries
• ./modules

If you wish to specify a custom global module, use:

modules:
 - custom_path/to/module

or alternatively:

module_paths:
 - custom_path/to/modules

module.yml fields

This describes the module.yml fields:

name: Project-Name             # The project name is what is used to find the module in an `import` statement
description: Does foo and bar  # This is a brief one-sentence overview of your project

version: 1.0.0                 # This specifies the version of the project. VSL uses semver.

stdlib: libvsl                 # Options include:
                               #  - none: no stdlib will be loaded
                               #  - name: in this case the provided name will be the name of the module to use as the stdlib

target: native                # What VSL should compile to. Use `vsl build --targets` for more information.

sources:                      # List of VSL source files. You can use globs
 - source.vsl

linkerArgs:                   # A list of arguments to the linker. Generally `ld`. You probably don't want to use this since you'll have difficulty finding cross-platform linkage steps.
 - ...

bindgen:                      # This uses `vsl bindgen` in the build-process which allows seamless integration with C-based libraries. You can provide a list of headers to use.
 - header: ...                # The path to the header file
   prefix: ...                # Some C libraries have a prefix. This specifies a list of prefixes to remove.
   name: ...                  # If provided, the header will not be globally imported. This specifies the `import` name
   autolink: ...              # If provided, the linker will be passed this value using `-l`