Package with both a library and a binary?

Question

I would like to make a Rust package that contains both a reusable library (where most of the program is implemented), and also an executable that uses it.

Assuming I have not confused any semantics in the Rust module system, what should my Cargo.toml file look like?

Bobbitt

Answer 1

Tok:tmp doug$ du -a

8   ./Cargo.toml
8   ./src/bin.rs
8   ./src/lib.rs
16  ./src

Cargo.toml:

[package]
name = "mything"
version = "0.0.1"
authors = ["me <[email protected]>"]

[lib]
name = "mylib"
path = "src/lib.rs"

[[bin]]
name = "mybin"
path = "src/bin.rs"

src/lib.rs:

pub fn test() {
    println!("Test");
}

src/bin.rs:

extern crate mylib; // not needed since Rust edition 2018

use mylib::test;

pub fn main() {
    test();
}

Washko

Thanks Doug, I will try it! Are the #![crate_name= ] and #![crate_type] annotations optional then? – Bobbitt

When you use Cargo, these options are unnecessary because Cargo passes them as compiler flags. If you run cargo build --verbose, you'll see them in rustc command line. – Perbunan

Do you know why [[bin]] is an array of tables? Why use [[bin]] and not [bin]? There doesn't seem to be any documentation on this. – Aricaarick

@Aricaarick It's the toml format specification [[x]] is an array once deserialized; ie. a single crate may produce multiple binaries, but only one library (thus [lib], not [[lib]]). You can have multiple bin sections. (I agree, this looks weird, but toml was always a controversial choice). – Washko

Is there a way to prevent it from compiling the binary when all I want is the lib? The binary has additional dependencies which I add through a feature called "binary", when I try to compile it without that feature, it fails to build. It complains that it can't find the crates that bin.rs is trying to import. – Margherita

@Person93 I think you can just use --bin / --lib to specify which you want to build, but I also believe you would then need to do something like [bin.bin_name] and use --bin bin_name. – Toilet

An example like this is of more use than pages of explanation in a book. – Naman

Is there a way to avoid hard-coding the name of the crate in the use statement? I tried with self:: and crate:: prefixes but the library function can't be found like that. Is there a way to use use relative paths in the binary when we have both src/lib.rs and src/bin.rs? – Stephanestephani

Doesn't work if crate-type = ["cdylib"], should mention that in answer – Ogham

Does it matter if I use the same name for the bin and lib (but using different files called main.rs and lib.rs? – Twigg

Answer 2

Simple

Create a src/main.rs that will be used as the defacto executable. You do not need to modify your Cargo.toml and this file will be compiled to a binary of the same name as the library.

The project contents:

% tree
.
├── Cargo.toml
└── src
    ├── lib.rs
    └── main.rs

Cargo.toml

[package]
name = "example"
version = "0.1.0"
edition = "2018"

src/lib.rs

use std::error::Error;

pub fn really_complicated_code(a: u8, b: u8) -> Result<u8, Box<dyn Error>> {
    Ok(a + b)
}

src/main.rs

fn main() {
    println!(
        "I'm using the library: {:?}",
        example::really_complicated_code(1, 2)
    );
}

And execute it:

% cargo run -q
I'm using the library: Ok(3)

Flexible

If you wish to control the name of the binary or have multiple binaries, you can create multiple binary source files in src/bin and the rest of your library sources in src. You can see an example in my project. You do not need to modify your Cargo.toml at all, and each source file in src/bin will be compiled to a binary of the same name.

The project contents:

% tree
.
├── Cargo.toml
└── src
    ├── bin
    │   └── mybin.rs
    └── lib.rs

Cargo.toml

[package]
name = "example"
version = "0.1.0"
edition = "2018"

src/lib.rs

use std::error::Error;

pub fn really_complicated_code(a: u8, b: u8) -> Result<u8, Box<dyn Error>> {
    Ok(a + b)
}

src/bin/mybin.rs

fn main() {
    println!(
        "I'm using the library: {:?}",
        example::really_complicated_code(1, 2)
    );
}

And execute it:

% cargo run --bin mybin -q
I'm using the library: Ok(3)

See also:

• How can I specify which crate `cargo run` runs by default in the root of a Cargo workspace?

Kalin

fits well with rust’s convention-over-configuration approach! both answers together and you have some great convenience and flexibility. – Pneumoencephalogram

extern crate example; is not required as of rust 2018, you can directly write use example::really_complicated_code; and use the function without naming the scope – Frump

Answer 3

An alternate solution is to not try to cram both things into one package. For slightly larger projects with a friendly executable, I've found it very nice to use a workspace.

Here, I create a binary project that includes a library inside of it, but there are many possible ways of organizing the code:

 % tree the-binary
the-binary
├── Cargo.toml
├── src
│   └── main.rs
└── the-library
    ├── Cargo.toml
    └── src
        └── lib.rs

Cargo.toml

This uses the [workspace] key and depends on the library:

[package]
name = "the-binary"
version = "0.1.0"
edition = "2018"

[workspace]

[dependencies]
the-library = { path = "the-library" }

src/main.rs

fn main() {
    println!(
        "I'm using the library: {:?}",
        the_library::really_complicated_code(1, 2)
    );
}

the-library/Cargo.toml

[package]
name = "the-library"
version = "0.1.0"
edition = "2018"

the-library/src/lib.rs

use std::error::Error;

pub fn really_complicated_code(a: u8, b: u8) -> Result<u8, Box<dyn Error>> {
    Ok(a + b)
}

And execute it:

% cargo run -q
I'm using the library: Ok(3)

---

There are two big benefits to this scheme:

1. The binary can now use dependencies that only apply to it. For example, you can include lots of crates to improve the user experience, such as command line parsers or terminal formatting. None of these will "infect" the library.

2. The workspace prevents redundant builds of each component. If we run cargo build in both the the-library and the-binary directory, the library will not be built both times — it's shared between both projects.

Kalin

This seems like a much better way to go. Obviously it's been years since the question was asked but people still struggle with organizing large projects. Is there a downside to using a workspace versus the selected answer above? – Bedcover

@Bedcover the biggest downside I can think of off the top of my head is that there are some tools that don't fully know how to deal with workspaces. They are kind of in a weird spot when interacting with existing tools that have some sort of "project" concept. I personally tend to take a continuum approach: I start with everything in main.rs, then break it up into modules as it gets bigger, finally splitting to src/bin when it's just a little bigger, then moving to a workspace when I start heavily reusing the core logic. – Kalin

thanks I will give it a spin. my current project has a couple of libs that are developed as part of the project but also used externally. – Bedcover

It builds and runs fine, but cargo test seems to ignore unit tests in lib.rs – Circle

@Circle I think you want cargo test --all – Kalin

@Kalin can you explain why you used [dependencies] instead of members = ["the-library"] – Overlying

@DylanKerler those control two different things. [dependencies] indicates a reliance on another package in order to compile. members specifies which packages should participate in the workspace. In this case, "An empty [workspace] table can be used with a [package] to conveniently create a workspace with the package and all of its path dependencies". – Kalin

Is it possible/advisable to make the main.rs part also a workspace member? Or should it definitely go at the top level? – Lanilaniard

Answer 4

You can put lib.rs and main.rs to sources folder together. There is no conflict and cargo will build both things.

To resolve documentaion conflict add to your Cargo.toml:

[[bin]]
name = "main"
doc = false

Movement

That would be covered by "Additionally, you can just create a src/main.rs that will be used as the defacto executable". in the other answer, no? And the documentation conflict is resolved by the accepted answer, right? You may need to clarify your answer to show why this is unique. It's OK to reference the other answers to build upon them. – Kalin