Solution examples

In this section I'm gonna cover how to use compiler.nvim .solution.toml files. Using a solution you can define the entry_point and output of the program(s) of your project. You can optionally define the arguments to pass to the compiler, and an executable to run after the compilation ends.

BASICS - Crating a solution file

Create a .solution.toml file in your working directory by using this template:

# Optional comments
[HelloWorld]
entry_point = "/path/to/my/entry_point_file/main.c"
output = "/path/where/the/program/will/be/written/hello_world"
arguments = ""

[SOLUTION]
executable = "/program/to/execute/after/the/solution/has/compiled/my_program"

Where every [entry] represents a program to compile

option	Description
[entry]	Anything inside the brackets will be ignored. Write anything you want to easily identify your program.
entry_point	Path of the file containing the entry point of the program.
output	Path where the compiled program will be written.
arguments	Are optional arguments to pass to the compiler. If you don't need them you can delete this option (to use the default arguments) or leave it as emtpy string to use none.

[SOLUTION] represents the executable to run after all programs in the solution have compiled. This section is optional and can be deleted safely.

Option	Description
[SOLUTION]	Anything inside the brackets will be ignored. But keeping the the default name [SOLUTION] is recommended.
executable	Path to a program to execute after the compilation finishes. It can be used multiple times. Any key containing the word "executable" will be detected. For example: executable1, executable2...

Please, respect the syntax of the config file, as we intentionally do not parse errors in order to keep the compiler code simple.

EXAMPLE 1 - Building more than one program

Here we are doing the same, but our solution compile multiple programs in parallel. One of them passes arguments to the compiler. Also the solution won't be executed afterwards, as it doesn't include the special section [SOLUTION] to specify the executable (see previous section).

[HelloWorld]
entry_point = "/path/to/my/entry_point_file/main.c"
output = "/path/where/the/program/will/be/written/hello_world"
arguments = "-Wall"

[HelloChurro]
entry_point = "/path/to/my/entry_point_file/main2.c"
output = "/path/where/the/program/will/be/written/hello_world2"
arguments = "-Wall"

EXAMPLE 2 - Solution for an interpreted language

When creating a .solution.toml file for an interpreted language like shell, python, ruby, perl, javascript, lua, do it this way:

[MyScript]
entry_point = "/path/to/my/entry_point_file/my_script.sh --some-argument=cool"
arguments = ""

[MyOtherCoolScript]
entry_point = "/path/to/my/entry_point_file/other_script.sh --cookie box --output yummy"
arguments = ""

By doing this, it is possible to pass arguments to your scripts. Interpreted languages don't need to be compiled, so anything you pass to entry_point will be executed directly.

Disclaimer: Often, it will be more convenient for you to just run your script on the terminal. That's totally fine. Please use the tool that suits your personal needs better.

EXAMPLE 3 - Passing arguments

This time we are gonna pass the argument -Wall to the c compiler, and --MyCoolArgument to the executable of the solution when compiling our [HELLO WORLD] project.

[HelloWorld]
entry_point = "/path/to/my/entry_point_file/main.c"
output = "/path/where/the/program/will/be/written/hello_world"
arguments = "-Wall"

[SOLUTION]
executable = "/program/to/execute/after/the/solution/has/compiled/my_program --MyCoolArgument=42"

If you are on an interpreted language, you would do the same, but arguments are for the interpreter, and program arguments are passed directly to the entry point

[MyScript]
entry_point = "/path/to/my/entry_point_file/my_script.sh --some-argument=cool"
arguments = "bash"

As you can see, by passing "bash" we are deciding what interpreter is gonna run the script. If you don't specify it, it will use your default interpreter. For other interpreted languages like lua, perl, ruby... arguments will be passed directly to their default interpreter.

EXAMPLE 4 - Passing dependencies

In this example we are passing all C dependencies in the ./dependencies directory

[HelloWorld]
entry_point = "/path/to/my/entry_point_file/main.c"
output = "/path/where/the/program/will/be/written/hello_world"
arguments = "-L/my/project/dependencies -l:*.so"

Please note that:

• You are passing the dependencies directly to the compiler, so the argument you need to pass will be different depending the language. You can check the compiler your current language use here.
• Dependencies will normally have the format .so or .dll and are treated in a different way than your normal program source files by the compiler.
• Real world projects will often use a building system (cmake, cargo, maven...), or a dotnet project file like .csproj to manage dependencies. If that's the case, use it instead of compiler.nvim.

TIP - Build solution without creating a .solution.toml file

It is possible to build a solution without creating a .solution.toml file.

compiler.nvim will search recursively on all folders under the current working directory for all the conventional entry point files with the same filetype as your current buffer. Then it will try to build all those entry point files.

For example: Imagine you have a repo with 3 different C projects, and you select "Build solution" but you haven't created a .solution.toml file. All the 3 projects will be built correctly anyway.

This is super convenient, as it will save you having to setup anything. The limitation is it won't run any program, as compiler.nvim has no way to determine what's the main executable of your solution. To cover this case of use, create a .solution.toml file.

Border cases

If you use Build solution on C# or java, by default the field executable of your .solution.toml will use the JIT virtual machine (mono or java) to run your program. But some times you might want to run something without the VM. You can do it like:

executable = "> /dev/null 2>&1; /path/to/my/program"

This only applies to C# and java: All other languages will always run executable directly on the terminal.

Example solution files for all languages

You can find example .solution.toml files for every language here under <your_language>/solution/.solution.toml.