cargo-culture

Overview

Cargo subcommand command that provides easy access to the cargo-culture-kit's default rules and provides an exemplar for the development of rule-checking binaries.

Getting Started

Dependencies

cargo-culture is a Rust project, and manages its dependencies with cargo, available as part of the standard Rust toolchain.

• rust

Building

For local program development, you can build cargo-culture with:

• Download the project repository

  git clone https://github.com/PolySync/cargo-culture.git
  cd cargo-culture/cargo-culture
  

• Execute a build

  cargo build
  

Installation

You can install cargo-culture directly from crates.io.

• Use cargo's built-in binary installation command

  cargo install cargo-culture
  

• Alternately, you may install from a local clone of the repository with:

  git clone https://github.com/PolySync/cargo-culture.git
  cd cargo-culture/cargo-culture
  cargo install
  

Usage

The easiest way to use cargo-culture is simply to run it from the root directory of a Rust project:

cd my_rust_project

cargo culture

• More detailed usage:

  $ cargo culture --help
  
  USAGE:
      cargo culture [FLAGS] [OPTIONS]
  
  FLAGS:
      -h, --help       Prints help information
      -V, --version    Prints version information
      -v, --verbose    If present, emit extraneous explanations and superfluous details
  
  OPTIONS:
          --culture-checklist-path <culture_checklist_file_path>
              The file location of the line-separated list of Rule descriptions to check for this project
  
          --manifest-path <manifest_path>
              The location of the Cargo manifest for the project to check [default: ./Cargo.toml]
  

Examples

• Running cargo culture with the default rules for a Rust project that needs a bit of work may look like the following:

  $ cargo culture
  Should have a well-formed Cargo.toml file readable by `cargo metadata` ... ok
  Should have a CONTRIBUTING file in the project directory. ... FAILED
  Should have a LICENSE file in the project directory. ... ok
  Should have a README.md file in the project directory. ... ok
  Should have a rustfmt.toml file in the project directory. ... FAILED
  Should have a file suggesting the use of a continuous integration system. ... FAILED
  Should `cargo clean` and `cargo build` without any warnings or errors. ... ok
  Should have multiple tests which pass. ... ok
  Should be under source control. ... ok
  Should be making an effort to use property based tests. ... ok
  culture result: FAILED. 7 passed. 3 failed. 0 undetermined.
  

• You can execute cargo culture checks against projects not in the current working directory with the --manifest-path option.

  cargo culture --manifest-path $HOME/some/other/project/Cargo.toml
  

• To apply only a subset of available rules, you can supply a .culture file in your project directory. This file should contain a line-separated list of Rule descriptions.

  $ cat > .culture << EOL
  Should have a LICENSE file in the project directory.
  Should have a README.md file in the project directory.
  EOL
  
  $ cargo culture
  Should have a LICENSE file in the project directory. ... ok
  Should have a README.md file in the project directory. ... ok
  culture result: ok. 2 passed. 0 failed. 0 undetermined.
  

• You can also select a subset of rules from a checklist file at a specific location by providing the --culture-checklist-path option.

  $ cat > my_culture_checklist.txt << EOL
  Should have a LICENSE file in the project directory.
  Should have a README.md file in the project directory.
  EOL
  
  $ cargo culture --culture-checklist-path my_culture_checklist.txt
  Should have a LICENSE file in the project directory. ... ok
  Should have a README.md file in the project directory. ... ok
  culture result: ok. 2 passed. 0 failed. 0 undetermined.
  

Tests

The cargo-culture tests are managed through the standard cargo-integrated Rust test framework, with additional enhancement through the proptest property based testing library.

Building

To build but not run the tests:

cargo build --tests

Running

To both build and run the tests:

cargo test

License

© 2018, PolySync Technologies, Inc.

• Zack Pierce email

Please see the LICENSE file for more details