Crate name for a library + a tool

help
1

I am about to publish a small command-line utility and I separated the project into a library (someone can be interested in using it outside of the tool) and a small binary. I the language was C I would name the library "libabrdump" and the tool "abrdump" but I see that Rust avoids the "lib" prefix in libraries. An option would be to call the library "abrdump" and the application "abrdump-cli" but I'd like to be able to do:

$ cargo install abrdump
$ abrdump [options] ...

and that implies that the name for the executable crate should be "abrdump". Or am I missing something?

There is an "official" naming scheme for projects like this one?

1 Like
2

If you want to make the tool available as a cargo subcommand, like 'cargo abrdump' , I think you have to name it 'cargo-abrdump' by convention. Because cargo discovers subcommands by looking for executables named cargo- in your $PATH.

3

No, I don't think making it a cargo subcommand is a good idea: it does not have anything to do with cargo or the Rust tooling ecosystem. I just want to be able to install it via cargo and invoke it using a short name ("abrdump").

4

If you're not thinking about publishing, then just do cargo install --path . and the bin should be invocable as 'abrdump'

5

If you follow the default layout of a Cargo project, you probably have a src/lib.rs file for your library and a src/main.rs file for your binary. The names of these two crates default to the package name (with dashes replaced by underscores for the library target). I wouldn't deviate from the default if you are unsure of what to do.

1 Like
6

I am thinking about publishing. I'd like to have opinions about how to name the two crates (library and executable), with the constraint that I'd like to be able to invoke the binary with "abrdump" instead of something like "abrdump-cli" or "abrdump-tool".

7

I have a workspace with two crates. I don't like the library to depends on cli-only libraries such as clap, for example.

8

Then the library crate will have to be published first as it is a dependency for the cli tool. You can use cargo search to check whether the name is available.

This shouldn't be needed if the crate name of the cli tool is 'abrdump' and the entry point is src/main.rs For naming the tool 'abrdump' and to be extra safe, you could add the following to the tools Cargo.toml, I am guessing you already have the path for the lib set up as you are successfully running it.


[[bin]]
name = "abrdump"

And there's literally the 'libc' crate out there (I get that it's just bindings but still) So I don't see why not name your library 'libabrdump' :'D

9

I don't think there is a default/official naming scheme for such a setup. You could however emulate the single-package binary + library crate default naming scheme, which is what I'd do, if I wouldn't want the -cli postfix in my binary. Say you have the package abrdump-cli with the binary and the abrdump package with the library. I'd rename the binary in the abrdump-cli package to abrdump. Users can then install it with cargo install abrdump-cli and use the abrdump command afterwards.

4 Likes
10

That actually sounds like best way to do it.

11

Thta's exactly what I wanted. Thank you very much.

1 Like
12

if you want to use a single package for both the library and binary, the cli tool can be conditional compiled (see required-features), and cli-only dependencies like clap can be optional. something like this:

# Cargo.toml
[package]
name = "abrdump"
# version, authors, license, ...

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

[[bin]]
name = "abrdump"
path = "src/main.rs"
required-features = ["cli"]

[dependencies.clap]
version = "..."
optional = true

[features]
default = []
cli = "dep:clap"

when you install the binary, you need to pass a --feature/-F flag:

$ cargo install -F cli abrdump

many packages on crates.io are using this scheme.

but I would prefer two packages, since optional dependencies are still resolved and appear in the lock file even if they are not enabled.

2 Likes