Skip to content

Latest commit

 

History

History
99 lines (67 loc) · 4.33 KB

README.md

File metadata and controls

99 lines (67 loc) · 4.33 KB
Raw

rust-magic-sys linux build status windows build status mac build status

Rust declarations for libmagic.

This cargo -sys package provides libmagic declarations for e.g. the magic binding.

Usage

magic-sys is available on crates.io so you can use it like this (in your Cargo.toml):

[dependencies]
magic-sys = "0.3"

The rustdoc is available on docs.rs.

Requirements

This crate requires the libmagic C library in version 5.

You need to specify your libmagic version by activating the matching magic-sys feature.
Each API version has a crate feature like "v5-38" (v5.38 is also the default), see Cargo.toml
If you use a different version of libmagic, adjust your configuration:

[dependencies.magic-sys]
version = "0.3"
default-features = false
features = ["v5-41"]

Note that those version features are additive, so "v5-41" implies "v5-40" and other previous versions.

libmagic needs to be installed in a standard location (also see issue #1).

On a Debian based Linux system this can be achieved like this:

sudo apt-get install libmagic1 libmagic-dev

On RHEL/Cent OS, Gentoo and others you will need to install the file package.

On Mac OS X you can use Homebrew:

brew install libmagic

Feedback for Windows (issue #2) support is appreciated!

You can use Microsoft's vcpkg via vcpkg-rs and cargo-vcpkg. If you choose the latter, that means you'll have to:

cargo install cargo-vcpkg
cargo vcpkg build

Afterwards, you can cargo build etc. your crate as usual.

MSRV

The Minimum Supported Rust Version (MSRV) is Rust 1.38 or higher.

This version might be changed in the future, but it will be done with a crate version bump.

Building

By default libmagic will be searched in the system library paths. If you need to use a different library or are cross-compiling, you can set the MAGIC_DIR and MAGIC_STATIC environment variables.

MAGIC_DIR, <TARGET>_MAGIC_DIR

Tells rustc where to find libmagic.so / libmagic.a. Can have a target-specific prefix like X86_64_UNKNOWN_LINUX_MUSL_MAGIC_DIR

MAGIC_STATIC, <TARGET>_MAGIC_STATIC

Controls static linking with libmagic. Enabled automatically if there's only a libmagic.a in the (provided) search path or if explicitly enabled like MAGIC_STATIC=true. Can have a target-specific prefix like X86_64_UNKNOWN_LINUX_MUSL_MAGIC_STATIC

Similarly MAGIC_STATIC=false can be used to choose to link libmagic dynamically. If unset but both libraries are available, the build will bail out with an error and you have to set one option explicitly.

vcpkg

The optional vcpkg integration has its own set of environment variables, see vcpkg crate docs. If you do not use cargo vcpkg build, you will have to either

  • vcpkg install libmagic and set the environment variables for your vcpkg root directory
  • vcpkg integrate install your vcpkg root user-wide

License

Licensed under either of

at your option.

Contribution

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.