Buckle is the Belte programming language compiler.
Arguments passed that are not associated with options will be interpreted as paths. Files will be treated as source files based on their file extension. Directories will treat all files within them (recursively) as source files based on their file extensions.
Displays a brief options summary.
Creates a starter build script. Optionally accepts a namespace name as the next argument. Only the –type and –debug options can be specified in addition.
The generated build script will be placed at Build.blt in the working directory, and an entry point will be created
at src/Program.blt. Both locations must be unoccupied.
Instead of using normal options, a build script can be used to drive the compilation. The build script is found
automatically by searching the working directory for a file named Build.blt. When using this option, only
–time, –info, and –debug options can be specified in addition. All other
arguments must be defined in the build script itself.
Optionally, the build script can be specified manually by passing it’s path as an argument immediately following build.
For relevant build modes, arguments can be passed with the – option.
Performs the same actions as build but then immediately runs the output if applicable. If the build mode does not produce a runnable output, this command fails. For build modes that execute immediately anyways (Executing, Evaluating, etc.), this command performs identically to build.
Arguments can be passed with the – option.
Build scripts are cached to reduce compilation overhead. The cache will automatically manage its size, but it can be completely deleted with this option (it will regenerate as needed).
Instead of producing an executable, the program is run immediately after being compiled. This is the default behavior when no build options are specified. There are two different methods in which the program can be run, and the compiler gets to pick which method to use.
Currently, the compiler will always choose –execute.
Invokes the Repl, a Read-Eval-Print Loop where the user can enter short code snippets and get the result immediately. The Repl is purely a command-line tool. If the -r or –repl option is passed, all other arguments are ignored.
For more information specifically on the Repl, see the Repl help doc.
Specifies the project type.
console (Default) |
An application that interfaces purely with the console. |
graphics |
An application that creates a window. |
dll |
Builds into a dynamically linked library. |
Specifies a type name to search for the entry point (and update point) symbols in. The type can be namespace qualified but cannot be nested.
Disables compiling with the higher-level Standard Library (collections, IO, etc.). Certain parts of the Standard Library are still compiled with where removing them would break core language functionality (such as primitive type definitions).
Instead of producing an executable, the program is run immediately after being compiled. Unlike the -i option, the method of running the program is always evaluation.
The program is run in a virtual environment. The Repl uses this mode.
Note that some features have restricted when using this option.
Instead of producing an executable, the program is run immediately after being compiled. Unlike the -i option, the method of running the program is always execution.
The program is emitted to a dynamic assembly and ran, offering better performance than –evaluate at the cost of slightly longer compile time.
Note that some features have restricted when using this option.
Instead of producing an executable, the program is transpiled into C# source code after initial compilation.
This option uses the same feature set as –dotnet with the additional restriction of disallowing inline IL.
Specifies the output file. You cannot specify this option in junction with -i, –evaluate, or –execute.
Specifies a language association for the following files instead of inferring association from file extension.
Currently, the only language association option is blt or belte which both mean Belte source files (this reflects
the default inferred file extensions). The option lasts for the rest of the command-line arguments or until it is
changes. Using none will reset to inferring file types from extensions.
Specifies an input file or directory, but in the case of a directory does not search recursively for input files.
All arguments after – will be passed to the program if evaluating or executing, otherwise they are ignored.
Specifies the maximum number of CPU cores to use. Without this option the compilation will be concurrent and use most cores if possible. Specifying a count of 1 will disable concurrent building.
The compiler stores all diagnostics of any severity. However, diagnostics are only logged or displayed if their severity is greater than or equal to the given severity level. The default is warning.
| Severity | Description |
|---|---|
| all | Everything is shown. |
| debug | Verbose information is shown. Used for debugging purposes. |
| info | Any information hidden by default. |
| warning | Information that usually suggests a non-required change. |
| error | Any problem that prevents full compilation. |
| fatal | Any problem that immediately stops the compiler as it cannot continue. |
Warnings are grouped into levels based on how “ignorable” they are. If 0 is passed as the warning level, warnings are suppressed even if the severity level indicates they should be logged/displayed. Warnings are logged/displayed if their warning level is less than or equal to the passed warning level. The default level is 1.
Suppresses specified warnings. Warnings should be comma delimited. Warnings should be specified using their codes.
Specifically avoids suppressing specific warnings, even if the severity level or warning level would suggest to do so. Warnings should be comma delimited. Warnings should be specified using their codes.
Treats all warnings of the given warning level and lower as if they were errors (i.e. build will fail on those warnings). If no warning level is provided, it defaults to 2.
When used in junction with –werror, avoids promoting certain warnings to errors.
When used without –werror, promotes certain warnings to errors.
Displays host machine information. The message will be in the form Host: [target]. For example, Host: win-x64.
Displays the compiler version information. The message will be in the form Version: Buckle [version]. The compiler
version will be in the form MAJOR.MINOR.PATCH.
Performs a dry run of the compiler. Prevents any file IO to occur. The compiler still displays normal information.
If compiling in a mode where the program would immediately run, the program is not run.
Deletes Repl submissions. If used with -r, the submissions are deleted before the Repl evaluates them.
Compile with .NET integration. The output will be a .NET DLL that can be used in a .NET project or ran depending on the project type.
Note that some features have restricted when using this option.
Specifies the module name used when .NET integration is enabled. Defaults to the name of the specified output file without the file extension, or a is no output file was specified. This option is purely used for debugging purposes and should not need to be used. This option is only valid in junction with the -d/–dotnet option.
Adds a reference when .NET integration is enabled. This reference is a path to a DLL that will be added to the program
and can then be referenced from within the program. This option is only valid in junction with the -d/–dotnet
option. If the specified path is a directory, all files ending in .dll inside of that directory (recursively) will be
added as references.
Optionally, ,flat can be appended to specify that directories should not be searched recursively. ,copy can be
appended to specify that the references libraries should be copied to the output directory.
Emits a .NET PDB file containing debugging symbols. Only emits the file if the -d/–dotnet option was specified.
Automatically includes certain library references. Each level includes all of the libraries from previous levels.
| l# | Libraries |
|---|---|
l0 |
System.Runtime.dll, System.IO.dll, System.Console.dll, System.Runtime.InteropServices.dll |
l1 |
Diagnostics.dll, Compiler.dll, Shared.dll, System.Collections.dll, System.Collections.Immutable.dll |
lall |
All .NET SDK libraries |
Displays how much time each stage of compilation took.
Displays additional information about the compilation process, such as file targets, compilation time, compiler version, etc. The user of the compiler does not need to know this information to properly use the compiler. This option is typically used for debugging.
The –noout option overrides –verbose, meaning that no information will be logged if both options are used. The –verbose option will automatically set the diagnostic reporting severity level to all, the warning level to 2 (unless explicitly set higher), and will also display timing information.
Specifies the path the –verbose mode will dump files. Defaults to the working directory.
Displays –verbose information without producing file artifacts.
If specified, the user will be prompted for any input after argument parsing but before any compilation, and then prompted again after compilation is finished. This allows attaching processes to the compiler before any work is done.
There is no setup required. No command-line arguments are needed apart from the files to run.
Example:
Program.blt
Console.PrintLine("Hello, world!");
Command Line
buckle Program.blt
Result (via stdout)
Hello, world!
Instead of passing compilation options directly, a build script can be used. To generate a starter build script, the
new command can be used. It accepts an optional project name and project type.
Some examples:
buckle new
buckle new MyProject
buckle new --type=dll
This command will create a Build.blt script in the working directory, and an entry point at src/Program.blt.
From there, you can use the build command:
buckle build
This will compile the project and place it into bin/<project name>.exe.
To see a hello world program, run the following commands in an empty directory:
buckle new
buckle build
./bin/project.exe
Both the -d and --type=dll options output a .NET dll. The former outputs a dll alongside a runtime config file and
an app host executable so that the program is ready to run by using <path/to/dll>.exe.
The --type=dll option outputs a dll that can be referenced by other applications, but is not a runnable application
itself. There is no entry point.
When building to a .NET DLL with the --debug flag, a PDB file is produced next to the output
assembly.