https://github.com/alinuxperson/build_script

A wrapper for build.rs instructions
https://github.com/alinuxperson/build_script

build build-script build-scripts build-tool build-tools rust rustlang

Last synced: 2 months ago
JSON representation

A wrapper for build.rs instructions

• Host: GitHub
• URL: https://github.com/alinuxperson/build_script
• Owner: ALinuxPerson
• License: mit
• Created: 2021-02-06T07:07:51.000Z (almost 4 years ago)
• Default Branch: master
• Last Pushed: 2023-05-25T20:26:52.000Z (over 1 year ago)
• Last Synced: 2024-10-12T13:23:37.474Z (2 months ago)
• Topics: build, build-script, build-scripts, build-tool, build-tools, rust, rustlang
• Language: Rust
• Homepage: https://crates.io/crates/build_script
• Size: 91.8 KB
• Stars: 16
• Watchers: 1
• Forks: 1
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

        


    
Build Script

    

        

    

    

        

    

    
A wrapper for build.rs instructions



# Why?

I made this because I felt like the way you pass instructions to `build.rs` makes it very easy to make mistakes 

(especially when using strings) and it just felt odd that rust doesn't provide an api or an official external crate 

(like [`rand`](https://crates.io/crates/rand)).

# Installation

Add this to your `Cargo.toml`:

```toml

[build-dependencies]

build_script = "0.2.0"

```

# Examples

```rust

use build_script::{cargo_rustc_link_lib, cargo_rustc_link_search, BuildScript, Instruction, Value};

fn main() {

    // basic instructions    

    build_script::cargo_rerun_if_changed("something.txt");

    build_script::cargo_rerun_if_env_changed("PKG_CONFIG");

    build_script::cargo_rustc_link_lib("somelibrary");

    build_script::cargo_rustc_link_lib_mapping(cargo_rustc_link_lib::Kind::DynamicLibrary, "somelibrary");

    build_script::cargo_rustc_link_search("something-else.txt");

    build_script::cargo_rustc_link_search_mapping(cargo_rustc_link_search::Kind::Crate, "something-else.txt");

    build_script::cargo_rustc_flags("-l ffi");

    build_script::cargo_rustc_cfg("key");

    build_script::cargo_rustc_cfg_mapping("key", "value");

    build_script::cargo_rustc_env("var", "value");

    build_script::cargo_rustc_cdylib_link_arg("flag");

    build_script::cargo_mapping("key", "value");

    // other, advanced instructions    

    let mut build_script = BuildScript::default();

    let instruction = {

        let value = Value::Singular("something".into());

        Instruction::new("instruction", value)

    };

    // add a custom instruction to the instruction stack    

    build_script.custom_instruction(instruction);

    // write all instructions to something (for this scenario, and also usually, its stdout)    

    build_script.build();

}

```

For more information see the documentation.

# Terminology

## Instruction

The instruction is what is passed to cargo. An example would be `cargo:rerun-if-env-changed=ENV`. This example will

also be dissected below.

The instruction is split into three parts:

### Prefix

The prefix is the string before the delimiter `:`: `cargo`.

Usually the prefix is `cargo`, however in this crate other, custom prefixes can be used for future compatibility in case

another prefix is added.

### Name

The name is the string in between the delimiters `:` and `=`: `rerun-if-env-changed`.

If the name is unknown, the instruction will automatically be a mapping (see below).

### Value

The value is the string after the delimiter `=`: `ENV`.

This represents the value of the instruction.

## Mapping

There is a type of instruction which is a mapping: `cargo:KEY=VALUE`.

This is, verbatim:

> Metadata, used by `links` scripts.

The source can be found [here](https://doc.rust-lang.org/cargo/reference/build-scripts.html).

This is used when an instruction name is unknown.