Libmagicxx

Libmagicxx is a C++ wrapper library over the Magic Number Recognition Library. It provides an easy-to-use interface through the magic class, enabling the identification of file types based on their content rather than file extensions.

Table of Contents

• Key Features
• Supported Platforms
• Project Status
• Code Quality
• Quick Start
• Downloading Libmagicxx
• Installing Libmagicxx
• Using Libmagicxx with CMake
• Examples
• Documentation
• Uninstalling Libmagicxx
• Contributing
• Security
• Source Code
• License
• Disclaimer

Key Features

• Modern C++ (C++23): Utilizes modern C++ standards and features, ensuring clean, efficient, and maintainable code.
• High-Level API: Provides a simple and intuitive high-level API for easy integration and use.
• Simple Integration with CMake: Easily integrate file type recognition into your CMake-based C++ projects.
• Cross Platform: Compatible with both Windows and Linux, ensuring broad usability and flexibility in various development environments.
• Comprehensive Documentation: Detailed documentation and examples to help you get started quickly and effectively.

Supported Platforms

• Linux (x86_64)
• Windows (x86_64)

Project Status

Code Quality

Quick Start

1. Download the latest release from the GitHub Releases page.
2. Install the package for your platform (see instructions below).
3. Link Libmagicxx in your CMake project (see usage instructions below).

Downloading Libmagicxx

You can download the latest release packages and source code directly from the GitHub Releases page.

• Latest Release: Download the most recent version of Libmagicxx, including pre-built packages for Linux and Windows, as well as the source code archive.
• All Releases: Browse and download previous versions.

After downloading, follow the installation instructions below for your platform.

Installing Libmagicxx

For Debian-based Linux distributions: Use the apt command to install the .deb package.

sudo apt install libmagicxx-<version>-linux-x86_64.deb

For Red Hat-based Linux distributions: Use the dnf command to install the .rpm package.

sudo dnf install libmagicxx-<version>-linux-x86_64.rpm

For Windows: Install the libmagicxx-<version>-windows-x86_64.exe package provided by the NSIS installer. Run the installer and follow the on-screen instructions to complete the installation.

Using Libmagicxx with CMake

Libmagicxx is designed to be easily integrated into CMake-based projects. To use Libmagicxx in your project after installation, follow these steps:

1. Add the following lines to the top level CMakeLists.txt file of your project to include and link Libmagicxx.

   find_package(magicxx REQUIRED)
    
   target_link_libraries(<name of your project>
       <PUBLIC or PRIVATE or INTERFACE> <recognition::magicxx or recognition::magicxx_static>
   )

2. Include the magic.hpp header file in your source files. Below is an example code snippet that demonstrates how to print the MIME type of the default database file using the magic class.

   #include <print>
   #include <iostream>
   #include <magic.hpp>
    
   auto main(int, char**) -> int
   {
       using namespace recognition;
       magic m{magic::flags::mime};
       std::println(std::cout, "{}", m.identify_file(magic::default_database_file));
       // possible output: text/x-file; charset=us-ascii
   }

Examples

For more examples, refer to the examples directory.

Documentation

For comprehensive guides, API references, and detailed information, visit the Libmagicxx Documentation Site. The source code for the documentation site is available in the documentation/html directory of the repository.

Uninstalling Libmagicxx

For Debian-based Linux distributions: Use the apt command to remove the installed .deb package.

sudo apt remove libmagicxx

For Red Hat-based Linux distributions: Use the dnf command to remove the installed .rpm package.

sudo dnf remove libmagicxx

For Windows: Use the uninstaller provided by the NSIS installer. Navigate to the "Add or Remove Programs" section in the Control Panel, find libmagicxx, and click "Uninstall."

Contributing

We welcome contributions of all kinds, including bug fixes, feature requests, documentation improvements, and code enhancements. Please see the CONTRIBUTING.md file for detailed guidelines on how to contribute or build Libmagicxx from source.

Security

For information on reporting security vulnerabilities, please see the SECURITY.md file.

Source Code

Explore the source code of Libmagicxx on GitHub.

License

Libmagicxx is licensed under the GNU Lesser General Public License Version 3. For more details, see the COPYING.LESSER file.

Other Licenses

• File and the Magic Number Recognition Library: See the COPYING file.
• GoogleTest: See the LICENSE file.
• Libgnurx: See the LICENSE file.

Disclaimer

This project is a personal hobby project developed in my own time and with my own resources. It is not affiliated with, endorsed by, or created on behalf of any employer, company, or organization. No proprietary or confidential information belonging to any employer or third party was used in its development. This project is not intended for any commercial purpose, income generation, or professional service.