Minilink - In search of better linker script composition

Template and register linker scripts with Rust's conditional compilation flags in hand.

More specifically, use minijinja for templating within build scripts. Linker scripts may templated and added to the linker script search path with register_template. Scripts may alternatively be added directly by using include_template, bypassing the need to manually configure -T link arguments.

Note that these function should only be called within build.rs scripts. Not only are errors handled with expect, but println! statements are used for emitting cargo build instructions.

Minijinja Environment

The minijinja render environment contains the following context entries:

• cfg: Map of all registered configuration options for the package being built. Names are lower cased. Values may be lists or singular strings. true cfg features are represented as empty strings ("") since Cargo does not create CARGO_CFG_<cfg> environment variables for boolean features whose values are false.

The following custom functions also registered:

• contains(<cfg_key>, <value>): Covers the case when a map value may be either a singular string or a list of strings. For example; contains(cfg.feature, "alloc") works when there is only one feature (i.e. cfg = "alloc"), or multiple (e.g. cfg = ["alloc", "std"]).

Example

The a templated linker script in ./ld/link.in.ld:

SECTIONS {
 .text : {
   {% if contains(cfg.feature, "some_feature") %}
   __feature = .;
   {% endif %}
 }
}

Can be registered in a build.rs with:

minilink::register_template("./ld/link.in.ld", "link.ld");

Which in turn produces a $OUT_DIR/link.ld containing:

SECTIONS {
 .text : {
   __feature = .;
 }
}

Features

• minijinja-defaults: Re-enables non-critical yet default minijinja features.

Minilink

Template and register linker scripts with Rust's conditional compilation flags in hand.

SECTIONS {
 .text : {
   {% if contains(cfg.feature, "some_feature") %}
   __feature = .;
   {% endif %}
 }
}

minilink::include_template("./ld/link.in.ld", "link.ld");

Further reading

• API Documentation
• Contributing
• Code of conduct