Anatomy of a Rust Program, Part I: Wink cargo.toml

This series of blog posts describe the structure of the wink command line program that I have written in rust and that I use to invoke other Windows and Linux programs from bash and Windows shells under Windows Subsystem for Linux. Especially as rust is well-documented and uses constructs much like many other languages, my goal is to describe the major structure of the program rather than every coding detail, including some elements specific to rust, but with minimal distracting links to documentation. This post introduces the project and its files.

I should start by repeating that I am not a programmer, and I am new to rust. I just started this learning project a few weeks ago. The following post from one of my other blogs provides a bit of background.

• Rust Command Line Tool to Access Windows Features and Commands – wslguy.net

This code and some notes for this project are at github.

• https://github.com/deliverystack/wink

The important files are as follows.

• /Cargo.toml: Defines the wink package, which contains one or more rust crates (cargo manages devops for rust).
• /src/main.rs: Defines the wink program, a binary (executable) crate in the wink package.
• /src/lib.rs: Defines a library crate specific to wink program in the wink package.
• /src/helperror.rs: Defines and implements the HelpError struct used to control rendering of usage information for the wink command.
• /src/winkconfig.rs: The WinkConfig struct used to model command line parameters to the wink command.
• /src/wsl.rs: Library specific to Windows Subsystem for Linux.
• /src/wsl/inv/invocable.rs: Metadata about a command that the operating system can invoke.
• /src/wsl/inv/invocablecategory.rs: A named list of invocable things.
• /src/wsl/inv/invocablecategorylist.rs: A list of categories of invocable things.
• /src/wsl/inv/invoker.rs: Invokes invocable things.
• /src/wsl/inv.rs: Groups the types defined in the files under the /src/wsl/inv directory under the wsl::inv path.
• /wince: Unix sh script uses cargo to manage building wink for Windows and Unix.

I seem to be working against rust conventions by storing each type in a separate file, but because I am storing configuration in code and have configured over 450 things, one of my types has hundreds of lines (more than a thousand lines, depending on line length limits enforced by rustfmt). Either I am working against convention or rust uses constructs unfamiliar to me that merge the contents of multiple files into a single rust path (namespace).

If crates in packages other thank my wink program could use them, then /src/wsl.rs as well as the /src/wsl directory and all of its contents could belong in a separate library crate in a separate library package, typically created using cargo.

In the wink package (which is really a file system directory containing a .toml file and a /src directory with either a /src/main.rs file or a /src/lib.rs file or both):

• /Cargo.toml: Defines the wink package, which contains one or more rust crates (cargo manages devops for rust).

I used the cargo new command to create the wink package. Under [package], name is important, as it determines the root name component of the path to library and binary crates in the package. Rust paths (namespaces) typically correspond to file system paths under the /src directory but also include paths in crates from external packages.

Under [dependencies], this package depends on crates for regular expressions, JSON serialization and deserialization, and coloring console output.

[package]
name = "wink"
version = "0.1.0"
authors = ["jw"]
edition = "2018"
include = ["src/**/*", "Cargo.toml"]

[dependencies]
regex = "1"
derive-new = "0.5"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
term = "*"

By convention, the rust compiler starts at /src/main.rs, which places an executable binary crate in the wink package, and includes /src/lib.rs, which places a library crate in the same package. These pieces of source code need to use rust path syntax with or without the use and mod keywords to reference any external crates, other crates and modules in this package, and even additional source code files in this package.

Running this package will call the main() function in /src/main.rs.

• Anatomy of a Rust Program, Part II: The main() Function in /src/main.rs – rustapopoulos.com
• Anatomy of a Rust Program, Part III: /src/lib.rs – rustapopoulos.com
• Anatomy of a Rust Program, Part IV: /src/helperror.rs – rustapopoulos.com
• Anatomy of a Rust Program, Part V: /src/winkconfig.rs – rustapopoulos.com
• Anatomy of a Rust Program, Part VI: /src/wsl.rs – rustapopoulos.com
• Anatomy of a Rust Program, Part VII: /src/wsl/inv.rs and /src/wsl/inv/*.rs – rustapopoulos.com
• Anatomy of a Rust Program, Part VIII: Anatomy of a Cargo Build Script – rustapopoulos.com