From 5f9374befa3a9ce4f88bc44facf87e8670898239 Mon Sep 17 00:00:00 2001 From: robot9001 Date: Sat, 30 Sep 2023 19:24:44 +0200 Subject: [PATCH] docs: Split project/crate README Signed-off-by: robot9001 --- .reuse/dep5 | 2 +- Cargo.toml | 1 + README-crate.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 75 ++++++++++++++++-------------------------------- src/lib.rs | 4 ++- 5 files changed, 106 insertions(+), 52 deletions(-) create mode 100644 README-crate.md diff --git a/.reuse/dep5 b/.reuse/dep5 index 210e36f3..48e71fb2 100644 --- a/.reuse/dep5 +++ b/.reuse/dep5 @@ -3,7 +3,7 @@ Upstream-Name: The `magic` Rust crate Upstream-Contact: robot9001 Source: https://github.com/robo9k/rust-magic -Files: Cargo.toml Cargo.lock README.md LICENSE.md CONTRIBUTING.md CHANGELOG.md SECURITY.md +Files: Cargo.toml Cargo.lock README.md README-crate.md LICENSE.md CONTRIBUTING.md CHANGELOG.md SECURITY.md Copyright: © The `magic` Rust crate authors License: MIT OR Apache-2.0 diff --git a/Cargo.toml b/Cargo.toml index 377c983a..5bbd3f1c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,7 @@ [package] name = "magic" description = "High level bindings for the `libmagic` C library" +readme = "README-crate.md" license = "MIT OR Apache-2.0" keywords = [ "magic", diff --git a/README-crate.md b/README-crate.md new file mode 100644 index 00000000..1737fdde --- /dev/null +++ b/README-crate.md @@ -0,0 +1,76 @@ + +[//]: # (This is the README for the `magic` crate only) + +[//]: # (The whole project has docs in https://github.com/robo9k/rust-magic ) + +High-level bindings for `libmagic` + +# About + +This crate provides bindings for the [`libmagic` C library]((https://www.darwinsys.com/file/)), +which recognizes the type of data contained in a file (or buffer) and can give you +a textual description, a MIME type and the usual file extensions. + +# Usage + +```rust +// only for Rust Edition 2018, see https://doc.rust-lang.org/edition-guide/rust-2021/prelude.html +use std::convert::TryInto; + +fn file_example() -> Result<(), Box> { + // Open a new configuration with flags + let cookie = magic::Cookie::open(magic::cookie::Flags::ERROR)?; + + // Load a specific database + // (so exact test text assertion below works regardless of the system's default database version) + let database = &["data/tests/db-images-png"].try_into()?; + // You can instead load the default database + //let database = &Default::default(); + + let cookie = cookie.load(database)?; + + let file = "data/tests/rust-logo-128x128-blk.png"; + + // Analyze the file + assert_eq!(cookie.file(file)?, "PNG image data, 128 x 128, 8-bit/color RGBA, non-interlaced"); + + Ok(()) +} +``` + +Check the [crate rustdoc](https://docs.rs/magic) for more details. + +# Repository + +The project's repository is [github.com/robo9k/rust-magic](https://github.com/robo9k/rust-magic) + +It contains the latest in-development version of the `magic` crate (might not be published to `crates.io` yet), +more [examples](https://github.com/robo9k/rust-magic/tree/main/examples) how to use the `magic` crate +as well as [issues](https://github.com/robo9k/rust-magic/issues) +and [discussions](https://github.com/robo9k/rust-magic/discussions). + +# MSRV + +The Minimum Supported Rust Version (MSRV) is Rust 1.56 or higher. + +This version might be changed in the future, but it will be done with a crate version bump. + +# Requirements + +By default, compiling the `magic` crate will (via the [`magic-sys` crate](https://crates.io/crates/magic-sys)) +search your system library paths for a shared library version of `libmagic` to link against. +For this to work, you need to install the development version of `libmagic` in a standard location: +```shell +$ # On Debian based Linux systems: +$ sudo apt-get install libmagic1 libmagic-dev + +$ # On macOS: +$ brew install libmagic + +$ # On Windows: +$ cargo install cargo-vcpkg +$ cargo vcpkg build +``` + +If you're cross-compiling, or need more control over which library is selected, +see [how to build `magic-sys`](https://crates.io/crates/magic-sys#building). diff --git a/README.md b/README.md index 323fa001..e23e2815 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,53 @@ + +[//]: # (This is the README for the whole project / Git repo) + +[//]: # (The crate has a separate README-crate.md ) + rust-magic [![build status](https://github.com/robo9k/rust-magic/actions/workflows/build.yml/badge.svg)](https://github.com/robo9k/rust-magic/actions/workflows/linux.yml) [![Documentation](https://docs.rs/magic/badge.svg)](https://docs.rs/magic) [![REUSE status](https://api.reuse.software/badge/github.com/robo9k/rust-magic)](https://api.reuse.software/info/github.com/robo9k/rust-magic) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5709/badge)](https://bestpractices.coreinfrastructure.org/projects/5709) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/robo9k/rust-magic/badge)](https://securityscorecards.dev/viewer/?uri=github.com/robo9k/rust-magic) [![codecov](https://codecov.io/gh/robo9k/rust-magic/graph/badge.svg?token=YnazJQdLXI)](https://codecov.io/gh/robo9k/rust-magic) ========== -[libmagic](https://www.darwinsys.com/file/) bindings for [Rust](https://www.rust-lang.org/). +[`libmagic`](https://www.darwinsys.com/file/) bindings for the [Rust programming language](https://www.rust-lang.org/). + +`libmagic` recognizes the type of data contained in a file (or buffer) and can give you +a textual description, a MIME type and the usual file extensions. # Usage -This [`magic` crate](https://crates.io/crates/magic) is published on the `crates.io` Rust package registry. +This project's [crate](https://doc.rust-lang.org/book/ch07-01-packages-and-crates.html) is +published on the [`crates.io` Rust package registry](https://crates.io/): the [`magic` crate](https://crates.io/crates/magic) -Use [`cargo add`](https://blog.rust-lang.org/2022/06/30/Rust-1.62.0.html#cargo-add) to [specify dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html): +In your Rust project, use [`cargo add`](https://blog.rust-lang.org/2022/06/30/Rust-1.62.0.html#cargo-add) +to [specify dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html): ```shell $ cargo add magic ``` +To install the latest in-development version instead: +```shell +$ cargo add --git https://github.com/robo9k/rust-magic +``` + You might be familiar with `libmagic`'s CLI; `file`: ```shell $ file data/tests/rust-logo-128x128-blk.png data/tests/rust-logo-128x128-blk.png: PNG image data, 128 x 128, 8-bit/color RGBA, non-interlaced ``` -You can implement something similar in Rust with the `magic` crate (see [examples/file-ish.rs](examples/file-ish.rs)): -```rust -// only for Rust Edition 2018, see https://doc.rust-lang.org/edition-guide/rust-2021/prelude.html -use std::convert::TryInto; - -fn file_example() -> Result<(), Box> { - // Open a new configuration with flags - let cookie = magic::Cookie::open(magic::cookie::Flags::ERROR)?; - - // Load a specific database - // (so exact test text assertion below works regardless of the system's default database version) - let database = &["data/tests/db-images-png"].try_into()?; - // You can instead load the default database - //let database = &Default::default(); - - let cookie = cookie.load(database)?; +You can implement something similar in Rust with the `magic` crate, see [crate README](README-crate.md): - let file = "data/tests/rust-logo-128x128-blk.png"; - - // Analyze the file - assert_eq!(cookie.file(file)?, "PNG image data, 128 x 128, 8-bit/color RGBA, non-interlaced"); - - Ok(()) -} -``` ```shell $ cargo run --example file-ish -- data/tests/rust-logo-128x128-blk.png PNG image data, 128 x 128, 8-bit/color RGBA, non-interlaced ``` -Read the [`magic` rustdoc](https://docs.rs/magic/#usage-example) for further examples and info. - -# MSRV - -The Minimum Supported Rust Version (MSRV) is Rust 1.56 or higher. - -This version might be changed in the future, but it will be done with a crate version bump. +For more details, check the `magic` [rustdoc](https://doc.rust-lang.org/rustdoc/index.html): [robo9k.github.io/rust-magic/magic](https://robo9k.github.io/rust-magic/magic/index.html) # Requirements -By default, compiling the `magic` crate will search your system library paths for a shared library version of `libmagic` to link against. For this to work, you need to install the development version of `libmagic` in a standard location: -```shell -$ # On Debian based Linux systems: -$ sudo apt-get install libmagic1 libmagic-dev - -$ # On MacOs: -$ brew install libmagic - -$ # On Windows: -$ cargo install cargo-vcpkg -$ cargo vcpkg build -``` +For the `magic` crate requirements, see [crate README](README-crate.md). -If you're cross-compiling, or need more control over which library is selected, see [how to build `magic-sys`](https://github.com/robo9k/rust-magic-sys#building). +For developing the `rust-magic` project, see [CONTRIBUTING](CONTRIBUTING.md). # License @@ -84,12 +59,12 @@ This project is licensed under either of at your option. -For further details, see [LICENSE.md](LICENSE.md). +For further details, see [LICENSE](LICENSE.md). # Security -See [SECURITY.md](SECURITY.md). +See [SECURITY](SECURITY.md). # Contribution -See [CONTRIBUTING.md](CONTRIBUTING.md). +See [CONTRIBUTING](CONTRIBUTING.md). diff --git a/src/lib.rs b/src/lib.rs index c8b985e2..c8988cde 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -70,6 +70,8 @@ //! Note that while some `libmagic` functions return somewhat structured text, e.g. MIME types and file extensions, //! the `magic` crate does not attempt to parse them into Rust data types since the format is not guaranteed by the C FFI API. //! +//! Check the [crate README](https://crates.io/crates/magic) for required dependencies and MSRV. +//! //! # Safety //! //! This crate is a binding to the `libmagic` C library and as such subject to its security problems. @@ -825,5 +827,5 @@ mod tests { } #[cfg(doctest)] -#[doc=include_str!("../README.md")] +#[doc=include_str!("../README-crate.md")] mod readme {}