Rust Package Management with Cargo: Beyond the Basics

# Cargo.toml

[dependencies]
# Basic dependency
serde = "1.0"

# Dependency with features
tokio = { version = "1.28", features = ["full"] }

# Dependency from git repository
rand = { git = "https://github.com/rust-random/rand", branch = "master" }

# Local path dependency
my_library = { path = "../my_library" }

# Platform-specific dependency
[target.'cfg(windows)'.dependencies]
winapi = "0.3"

# Development dependencies
[dev-dependencies]
criterion = "0.5"

# Build dependencies
[build-dependencies]
cc = "1.0"

[dependencies]
# Exact version
exact = "=1.0.0"

# Greater than or equal to
minimum = ">=1.0.0"

# Less than
maximum = "<2.0.0"

# Range
range = ">1.0.0, <2.0.0"

# Compatible with (^)
compatible = "^1.2.3"  # >= 1.2.3, < 2.0.0

# Tilde requirements (~)
patch_updates = "~1.2.3"  # >= 1.2.3, < 1.3.0

# Wildcard
minor_updates = "1.2.*"  # >= 1.2.0, < 1.3.0

# Cargo.toml

[features]
default = ["std", "json"]
std = ["serde/std"]
json = ["serde_json"]
xml = ["serde_xml"]
full = ["json", "xml", "compression"]
compression = []

[dependencies]
serde = { version = "1.0", default-features = false, optional = true }
serde_json = { version = "1.0", optional = true }
serde_xml = { version = "0.9", optional = true }

// src/lib.rs

#[cfg(feature = "json")]
pub mod json {
    pub fn parse_json(input: &str) -> Result<Value, Error> {
        // JSON parsing implementation
    }
}

#[cfg(feature = "xml")]
pub mod xml {
    pub fn parse_xml(input: &str) -> Result<Value, Error> {
        // XML parsing implementation
    }
}

#[cfg(feature = "compression")]
pub mod compression {
    pub fn compress(data: &[u8]) -> Vec<u8> {
        // Compression implementation
    }
    
    pub fn decompress(data: &[u8]) -> Result<Vec<u8>, Error> {
        // Decompression implementation
    }
}

# Cargo.toml

[dependencies]
serde = "1.0"
log = "0.4"

[patch.crates-io]
# Use a local version of serde
serde = { path = "../my-fork-of-serde" }

# Use a specific git commit of log
log = { git = "https://github.com/rust-lang/log", rev = "abc123" }

# .cargo/config.toml

[source.crates-io]
replace-with = "vendored-sources"

[source.vendored-sources]
directory = "vendor"

# Vendor dependencies
cargo vendor

# Cargo.toml (root)

[workspace]
members = [
    "core",
    "cli",
    "web",
    "utils",
]

# Optimize build scripts and proc macros even in debug mode
[profile.dev.build-override]
opt-level = 3

# Optimize dependencies in debug mode
[profile.dev.package."*"]
opt-level = 2

# core/Cargo.toml

[package]
name = "my_project_core"
version = "0.1.0"
edition = "2021"

[dependencies]
serde = { version = "1.0", features = ["derive"] }

# cli/Cargo.toml

[package]
name = "my_project_cli"
version = "0.1.0"
edition = "2021"

[dependencies]
my_project_core = { path = "../core" }
clap = { version = "4.3", features = ["derive"] }

# Build all workspace members
cargo build --workspace

# Test all workspace members
cargo test --workspace

# Run a specific package
cargo run -p my_project_cli

# Check a specific package
cargo check -p my_project_core

# Update dependencies for the entire workspace
cargo update --workspace

# Cargo.toml (root)

[workspace]
members = [
    "core",
    "cli",
    "web",
]

# Shared dependencies
[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.28", features = ["full"] }
log = "0.4"
env_logger = "0.10"

# Shared development dependencies
[workspace.dev-dependencies]
criterion = "0.5"
mockall = "0.11"

# Shared settings
[workspace.package]
authors = ["Your Name <[email protected]>"]
license = "MIT OR Apache-2.0"
repository = "https://github.com/yourusername/my_project"

# core/Cargo.toml

[package]
name = "my_project_core"
version = "0.1.0"
edition = "2021"
# Inherit shared settings
authors.workspace = true
license.workspace = true
repository.workspace = true

[dependencies]
# Use workspace dependencies
serde.workspace = true
log.workspace = true

[dev-dependencies]
# Use workspace dev-dependencies
criterion.workspace = true

# Cargo.toml (root, virtual manifest)

[workspace]
members = [
    "packages/*",
    "tools/*",
]
exclude = [
    "packages/deprecated",
    "tools/experimental",
]

[workspace.package]
authors = ["Your Name <[email protected]>"]
license = "MIT OR Apache-2.0"

# Cargo.toml

[package]
name = "my_package"
version = "0.1.0"
edition = "2021"
authors = ["Your Name <[email protected]>"]
description = "A package that does awesome things"
license = "MIT OR Apache-2.0"
repository = "https://github.com/yourusername/my_package"
documentation = "https://docs.rs/my_package"
homepage = "https://my-package.example.com"
readme = "README.md"
keywords = ["awesome", "cool", "amazing"]
categories = ["development-tools", "api-bindings"]

# Exclude files from the package
exclude = [
    "assets/large-files/*",
    "tests/fixtures/*",
    ".github/*",
]

# Include only specific files in the package
# include = [
#     "src/**/*",
#     "Cargo.toml",
#     "README.md",
#     "LICENSE-*",
# ]

# Check if the package is ready for publishing
cargo publish --dry-run

# Verify the package contents
cargo package --list

# Publish the package
cargo publish

# Publish with a specific registry
cargo publish --registry alternative-registry

# Bump version
cargo install cargo-edit
cargo set-version 0.2.0

# Bump version and update changelog
cargo install cargo-release
cargo release --dry-run minor
cargo release minor

# Cargo.toml

# Configure docs.rs build
[package.metadata.docs.rs]
# Features to enable when building documentation
features = ["full"]
# Custom rustdoc flags
rustdoc-args = ["--cfg", "docsrs"]
# Default target
default-target = "x86_64-unknown-linux-gnu"
# Additional targets to build documentation for
targets = ["wasm32-unknown-unknown"]

// src/lib.rs

// Documentation for docs.rs
#[cfg(docsrs)]
pub mod docs {
    //! Documentation that is only visible on docs.rs
}

// Feature-gated API that will be documented on docs.rs
#[cfg(feature = "full")]
pub mod advanced {
    //! Advanced features that are only available with the "full" feature
}

// build.rs

use std::env;
use std::fs;
use std::path::Path;

fn main() {
    // Get the output directory
    let out_dir = env::var("OUT_DIR").unwrap();
    let dest_path = Path::new(&out_dir).join("generated.rs");
    
    // Generate code
    let generated_code = "pub const ANSWER: u32 = 42;";
    fs::write(&dest_path, generated_code).unwrap();
    
    // Tell Cargo to rerun this script if build.rs changes
    println!("cargo:rerun-if-changed=build.rs");
    
    // Tell Cargo to rerun this script if any file in the data directory changes
    println!("cargo:rerun-if-changed=data/");
    
    // Tell Cargo to link against the specified native library
    println!("cargo:rustc-link-lib=sqlite3");
    
    // Set a cfg flag
    println!("cargo:rustc-cfg=feature=\"generated\"");
}

// src/lib.rs

// Include the generated code
include!(concat!(env!("OUT_DIR"), "/generated.rs"));

#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_answer() {
        assert_eq!(ANSWER, 42);
    }
}

# Cargo.toml

[lib]
proc-macro = true

[dependencies]
syn = "2.0"
quote = "1.0"
proc-macro2 = "1.0"

// src/lib.rs

use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, DeriveInput};

#[proc_macro_derive(MyDerive)]
pub fn my_derive(input: TokenStream) -> TokenStream {
    // Parse the input tokens into a syntax tree
    let input = parse_macro_input!(input as DeriveInput);
    let name = input.ident;
    
    // Build the output
    let expanded = quote! {
        impl #name {
            pub fn hello_world(&self) -> &'static str {
                "Hello, World!"
            }
        }
    };
    
    // Convert back to TokenStream
    TokenStream::from(expanded)
}

// tools/src/bin/cargo-my-command.rs

fn main() {
    // This will be invoked as `cargo my-command`
    println!("Hello from custom Cargo command!");
}

# Install the custom command
cargo install --path tools

# Run the custom command
cargo my-command

# ~/.cargo/config.toml

# Default settings for all projects
[build]
jobs = 8  # Number of parallel jobs
target-dir = "/tmp/cargo-build"  # Custom target directory

[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=lld"]

[target.x86_64-pc-windows-msvc]
rustflags = ["-C", "target-feature=+crt-static"]

[registries]
my-registry = { index = "https://my-registry-index.example.com" }

[net]
retry = 3  # Number of retries for network requests
git-fetch-with-cli = true  # Use the git CLI for git operations

# .cargo/config.toml

[build]
target = "wasm32-unknown-unknown"  # Default target

[alias]
b = "build"
t = "test"
r = "run"
c = "check"
br = "build --release"

[env]
RUST_LOG = "debug"

# Set environment variables for Cargo
export CARGO_TARGET_DIR=target/custom
export RUSTFLAGS="-C target-cpu=native"
export RUSTDOCFLAGS="--html-in-header header.html"

# Run Cargo with the environment variables
cargo build

# Install cargo-tree
cargo install cargo-tree

# View the dependency tree
cargo tree

# View the dependency tree for a specific package
cargo tree -p serde

# Find duplicate dependencies
cargo tree -d

# Find features that are enabled
cargo tree -f

# Install cargo-audit
cargo install cargo-audit

# Check for vulnerabilities
cargo audit

# Update vulnerable dependencies
cargo audit fix

# Install cargo-license
cargo install cargo-license

# Check licenses of dependencies
cargo license

# Check licenses with detailed output
cargo license --json

# Install cargo-bloat
cargo install cargo-bloat

# Analyze binary size
cargo bloat --release

# Analyze binary size by crate
cargo bloat --release --crates

# Analyze binary size by function
cargo bloat --release --function

# .github/workflows/ci.yml

name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
          override: true
          components: rustfmt, clippy
      
      - name: Cache dependencies
        uses: actions/cache@v3
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
      
      - name: Check formatting
        uses: actions-rs/cargo@v1
        with:
          command: fmt
          args: --all -- --check
      
      - name: Lint
        uses: actions-rs/cargo@v1
        with:
          command: clippy
          args: -- -D warnings
      
      - name: Build
        uses: actions-rs/cargo@v1
        with:
          command: build
      
      - name: Test
        uses: actions-rs/cargo@v1
        with:
          command: test
      
      - name: Publish
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        uses: actions-rs/cargo@v1
        with:
          command: publish
          args: --token ${{ secrets.CRATES_IO_TOKEN }}

# .github/workflows/cross-platform.yml

name: Cross-Platform

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        rust: [stable, beta, nightly]
        exclude:
          - os: windows-latest
            rust: nightly
    
    runs-on: ${{ matrix.os }}
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: ${{ matrix.rust }}
          override: true
      
      - name: Build
        uses: actions-rs/cargo@v1
        with:
          command: build
      
      - name: Test
        uses: actions-rs/cargo@v1
        with:
          command: test

# Check for errors without building
cargo check

# Check with all features enabled
cargo check --all-features

# Check for a specific target
cargo check --target wasm32-unknown-unknown

# Automatically fix warnings
cargo fix

# Fix code to prepare for a new edition
cargo fix --edition

# Only apply suggested fixes
cargo fix --allow-staged

# Run clippy lints
cargo clippy

# Run specific lints
cargo clippy -- -W clippy::pedantic

# Apply clippy suggestions
cargo clippy --fix

# Format code
cargo fmt

# Check if code is formatted
cargo fmt -- --check

# Format specific files
cargo fmt -- src/main.rs src/lib.rs

# Generate documentation
cargo doc

# Generate documentation and open it in a browser
cargo doc --open

# Generate documentation including private items
cargo doc --document-private-items

# Generate Cargo.lock
cargo generate-lockfile

# Update Cargo.lock
cargo update

# Update a specific dependency
cargo update -p serde

# Verify Cargo.lock is up-to-date
cargo verify-project

# Cargo.toml

# Follow semantic versioning for your package
[package]
version = "1.2.3"  # Major.Minor.Patch

# Use appropriate version requirements for dependencies
[dependencies]
# For libraries: use compatible versions
serde = "^1.0"  # >= 1.0.0, < 2.0.0

# For applications: pin exact versions
tokio = "=1.28.0"

# Cargo.toml

[dependencies]
# Use specific features instead of full dependencies
tokio = { version = "1.28", features = ["rt", "macros"], default-features = false }
serde = { version = "1.0", features = ["derive"], default-features = false }

# Avoid unnecessary dependencies
# Bad: Including full regex for simple string matching
# regex = "1.8"

# Good: Use standard library for simple cases
# Use String::contains, String::starts_with, etc.

# Cargo.toml

# Optimize build scripts and proc macros even in debug mode
[profile.dev.build-override]
opt-level = 3

# Optimize dependencies in debug mode
[profile.dev.package."*"]
opt-level = 2

# Optimize binary size in release mode
[profile.release]
opt-level = 3
lto = "thin"
codegen-units = 1
strip = true  # Strip symbols