Skip to content

Latest commit

 

History

History
141 lines (92 loc) · 5.61 KB

README.md

File metadata and controls

141 lines (92 loc) · 5.61 KB
Raw

rust-magic-sys 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.39 or newer.

libmagic

If you don't want to configure the build, libmagic has to be available in a standard location for either pkg-config or vcpkg, see Building.

On a Debian based Linux system such as Ubuntu 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 cargo-vcpkg:

cargo install cargo-vcpkg
cargo vcpkg build

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

Version features

The libmagic API is extended with new backwards-compatible features every now and then.
To use newly added libmagic functionality, you need to use a corresponding libmagic version.

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.

If you want to use a newer/different libmagic version, you will have to link it accordingly.

MSRV

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

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

Building

To determine which libmagic to link against, this crate uses pkg-config and vcpkg.

The crate does not offer to link a against a bundled libmagic version, see issue #4.

In general you can link statically or dynamically against libmagic.

With static linkage your binary/library includes the libmagic code and does not have a run-time dependency.

With dynamic linkage your binary/library does not include the libmagic code and does have a run-time dependency on a libmagic.dll / libmagic.so / libmagic.dylib depending on your platform (Windows / Linux / macOS).
You might have to ship this libmagic shared library with your binary/library if you do not expect your users to have a compatible version installed on their system.

You might want to ship a copy of the default libmagic / file database with your binary/library if you do not expect your users to have a compatible libmagic installed on their system.

pkg-config

The pkg-config crate feature uses the pkg-config crate, so check its documentation for details.

You can use e.g. the following environment variables:

  • LIBMAGIC_NO_PKG_CONFIG if set, will skip pkg-config
  • LIBMAGIC_STATIC if set, instructs pkg-config to link statically
  • LIBMAGIC_DYNAMIC if set, instructs pkg-config to link dynamically

By default dynamic linkage is used.

vcpkg

The vcpkg crate feature uses the vcpkg crate, so check its documentation for details.

You can use e.g. the following environment variables:

  • VCPKGRS_NO_LIBMAGIC if set, will skip vcpkg
  • VCPKGRS_DYNAMIC if set, instructs vcpkg to link dynamically

By default static linkage is used.

You can use vcpkg standalone or by using cargo-vcpkg.

If you do not use cargo vcpkg build, you will have to either

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

Override

If you disable or skip both pkg-config and vcpkg the magic-sys build script will fail.
Especially linking statically to libmagic requires additional libraries that depend on your version and system.

You can skip the magic-sys build script entirely by overriding it.
This is an option if you want to use neither pkg-config nor vcpkg.

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.