XTasks

Essential tools and tasks for Rust projects using the xtask pattern, simplifying common build and development workflows.

Table of Contents

• XTasks
  • Table of Contents
  • Overview
  • Features
    • 1. Enhanced File Operations (ops.rs)
    • 2. XTasks Library Introduction (lib.rs)
    • 3. Convenient Macros (macros.rs)
    • 4. Cargo XTask Integration (tasks.rs)
    • 5. Binary Entry Point (main.rs)
    • 6. Cargo Build Configuration (powerset.rs)
    • 7. Dependency Analysis (bloat.rs)
    • 8. CI Configuration Management (ci.rs)
    • 9. Dynamic Documentation Generation (docs.rs)
  • Getting Started
    • Prerequisites
    • Installation
  • Usage
  • Running the Tests
  • Examples
    • File Operations Example
    • Macro Usage Example
    • CI Configuration Example
  • Semantic Versioning Policy
  • License
  • Contribution
  • Acknowledgements

Overview

XTasks is a comprehensive Rust library designed to facilitate common operations and tasks in projects that adhere to the xtask pattern. This pattern is prevalent in the Rust ecosystem, where it is used to define custom build, test, and deployment scripts within a project’s workspace.

Features

1. Enhanced File Operations (ops.rs)

• Filesystem Utilities: Provides functions for common filesystem operations like file copying and removal.
• Glob Pattern File Removal: Supports removing files based on glob patterns, aiding in cleaning up temporary or generated files.

2. XTasks Library Introduction (lib.rs)

• Simplifies build and development workflows for Rust projects using the xtask pattern.

3. Convenient Macros (macros.rs)

• Enhanced Print Macros: Redefined println! and print! macros for formatted console output.
• Assertion Macros: Custom macros for asserting conditions in the code, enhancing readability and functionality.

4. Cargo XTask Integration (tasks.rs)

• Streamlined Development Workflows: Provides tasks for development, testing, and maintenance of Rust projects.
• Documentation Automation: Facilitates automatic generation of project documentation.
• Continuous Integration Support: Implements tasks for CI to ensure code quality and stability.

5. Binary Entry Point (main.rs)

• Central entry point for the XTasks binary, integrating various components of the project.

6. Cargo Build Configuration (powerset.rs)

• Powerset Feature Management: Manages combinations of features for cargo build runs, allowing depth specification for feature combinations.

7. Dependency Analysis (bloat.rs)

• Analyzes dependencies to identify their impact on build size, aiding in build optimization.

8. CI Configuration Management (ci.rs)

• Flexible CI Settings: Configures settings for CI runs, including compiler version choices and Clippy lint options.

9. Dynamic Documentation Generation (docs.rs)

• Automatically generates and updates documentation in response to source code changes.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

You will need Rust and Cargo installed on your system. If you don't have them installed, you can install them from the official Rust website.

Installation

To use XTasks, add it as a dependency to your Cargo.toml file:

[dependencies]
xtasks = "0.0.2"

Then, in your lib.rs or main.rs file, add:

extern crate xtasks;

Usage

You can use XTasks to simplify and standardize the process of building, testing, and deploying your Rust projects. For more detailed usage examples, please refer to the library's documentation.

Running the Tests

To run the tests, use the following command:

cargo test

Examples

This section provides basic examples to demonstrate how to use some of the key features of XTasks in your Rust projects.

File Operations Example

Using the enhanced file operations from ops.rs:

// Assuming you've included the `xtasks` crate
use xtasks::file_operations;

fn main() {
    // Copying a file
    file_operations::copy("path/to/source.file", "path/to/destination.file").unwrap();

    // Removing files based on a glob pattern
    file_operations::remove_files("path/to/temporary/*.tmp").unwrap();
}

Macro Usage Example

Implementing the custom println! and assert! macros:

// Importing macros from xtasks
use xtasks::{println, assert};

fn main() {
    // Using the enhanced println! macro
    println!("This is a formatted {} message", "output");

    // Using a custom assert! macro
    assert!(2 + 2 == 4, "Math error: 2 + 2 should equal 4");
}

CI Configuration Example

Configuring and running CI tasks with ci.rs:

use xtasks::ci::CI;

fn main() {
    let ci_config = CI::builder()
        .nightly(true)
        .enable_clippy_lints(true)
        .build()
        .unwrap();

    ci_config.run();
}

Semantic Versioning Policy

For transparency into our release cycle and in striving to maintain backward compatibility, XTasks follows semantic versioning.

License

The project is licensed under the terms of both the MIT license and the Apache License (Version 2.0).

• Apache License, Version 2.0
• MIT license

Contribution

We welcome all people who want to contribute. Please see the contributing instructions for more information.

Contributions in any form (issues, pull requests, etc.) to this project must adhere to the Rust's Code of Conduct.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Acknowledgements

A big thank you to all the awesome contributors of xtasks for their help and support.

A special thank you goes to the Rust Reddit community for providing a lot of useful suggestions on how to improve this project.