xtasks/lib.rs
1// Copyright © 2023 xtasks. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3
4//!
5//! # `XTasks`
6//!
7//! [][00]
8//!
9//! ## Essential tools and tasks for Rust projects using the xtask pattern, simplifying common build and development workflows.
10//!
11//! [](https://crates.io/crates/xtasks "Crates.io")
12//! [](https://lib.rs/crates/xtasks "Lib.rs")
13//! [](https://opensource.org/license/apache-2-0/ "MIT or Apache License, Version 2.0")
14//! [](https://www.rust-lang.org "Rust")
15//!
16//! `xtasks` is a comprehensive Rust library designed to facilitate common operations and tasks
17//! in projects that adhere to the `xtask` pattern. This pattern is prevalent in the Rust ecosystem,
18//! where it is used to define custom build, test, and deployment scripts within a project’s workspace.
19//!
20//! ## Overview
21//!
22//! The library aims to simplify and standardize the process of handling frequent project-related tasks,
23//! offering a range of functionalities from basic file operations to intricate continuous integration
24//! workflows and documentation generation. It provides both low-level building blocks and high-level
25//! abstractions to cater to different use cases and levels of complexity.
26//!
27//! ## Modules
28//!
29//! - **`ops`**: This module contains fundamental building block operations such as file manipulation,
30//! confirmation prompts, and command execution. It serves as the foundation for more complex tasks.
31//!
32//! - **`tasks`**: Here, you'll find higher-level functionalities and default implementations for common
33//! project tasks, streamlining processes like code coverage analysis, CI/CD workflows, and more.
34//!
35//! - **`macros`**: This module offers a collection of convenient macros designed to expedite common
36//! operations, reducing boilerplate and enhancing code readability.
37//!
38//! ## Features
39//!
40//! - **Simplicity**: Provides a user-friendly API, making it easy for developers to integrate `xtasks`
41//! into their projects and start automating their workflows.
42//!
43//! - **Extensibility**: Designed with extensibility in mind, allowing developers to easily add new tasks
44//! and customize existing ones to meet the unique needs of their projects.
45//!
46//! - **Robustness**: Incorporates thorough error handling and validation, ensuring that tasks are executed
47//! reliably and any issues are promptly reported.
48//!
49//! - **Integration**: Seamlessly integrates with existing Rust tooling and conventions, ensuring a smooth
50//! development experience.
51//!
52//! ## Usage
53//!
54//! To integrate `xtasks` into your project, add it as a dependency in your `Cargo.toml` file. Once added,
55//! you can leverage the various functionalities and tasks provided by the library. Here’s an example on
56//! how to use a function from the `ops` module:
57//!
58//! ```rust
59//! use xtasks::ops::clean_files;
60//!
61//! # fn run() -> anyhow::Result<()> {
62//! clean_files("target/debug/*.tmp")?;
63//! # Ok(())
64//! # }
65//! # run().unwrap();
66//! ```
67//!
68//! ## Contributing
69//!
70//! Contributions to `xtasks` are warmly welcomed. Whether it’s enhancing existing features, fixing bugs,
71//! or implementing new functionalities, your input is valuable. Please ensure that all contributions are
72//! accompanied by comprehensive documentation and tests, adhering to the project’s coding standards.
73//! Please see [CONTRIBUTING.md][03] for details on how to contribute.
74//!
75//! ## License
76//!
77//! `xtasks` is distributed under the terms of both the MIT license and the Apache License (Version 2.0),
78//! providing flexibility and ensuring open-source readiness.
79//!
80//! - [Apache License, Version 2.0][04]
81//! - [MIT license][05]
82//!
83//! Enjoy automating your workflows with `xtasks`!
84//!
85//! [00]: https://xtasks.pro "XTasks"
86//! [01]: https://github.github.com/gfm/ "GitHub Flavoured Markdown"
87//! [02]: https://www.rust-lang.org/ "Rust"
88//! [03]: https://xtasks.pro/contribute/index.html "Contribute to XTasks"
89//! [04]: https://opensource.org/license/apache-2-0/ "Apache License, Version 2.0"
90//! [05]: http://opensource.org/licenses/MIT "MIT license"
91
92#![allow(clippy::must_use_candidate)]
93#![deny(dead_code)]
94#![deny(rustc::existing_doc_keyword)]
95#![doc(
96 html_favicon_url = "https://kura.pro/xtasks/images/favicon.ico",
97 html_logo_url = "https://kura.pro/xtasks/images/logos/xtasks.webp",
98 html_root_url = "https://docs.rs/xtasks"
99)]
100#![forbid(missing_debug_implementations)]
101#![forbid(missing_docs)]
102#![forbid(unreachable_pub)]
103#![forbid(unsafe_code)]
104#![crate_name = "xtasks"]
105#![crate_type = "lib"]
106
107/// The `macros` module offers a collection of convenient macros designed to expedite common operations,
108/// reducing boilerplate and enhancing code readability.
109pub mod macros;
110/// The `ops` module contains fundamental building block operations such as file manipulation,
111/// confirmation prompts, and command execution. It serves as the foundation for more complex tasks.
112pub mod ops;
113/// The `tasks` module contains higher-level functionalities and default implementations for common
114/// project tasks, streamlining processes like code coverage analysis, CI/CD workflows, and more.
115pub mod tasks;