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
• Magic States
• Libmagicxx CMake Package Variables
• 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
   }

Magic States

Libmagicxx's magic class can be in several states, which affect its usability:

1. Closed Magic

• The magic is considered closed if it has not been opened or has been explicitly closed using the close() method.

• In this state, it cannot be used for file type identification.

• Methods that require an open magic (e.g., identify_file, get_flags, etc.) will throw or return errors if called.

• is_open() returns false.

• is_database_loaded() returns false.

• is_valid() returns false.

2. Opened Magic Without Database

• The magic is open (after open()), but no database file has been loaded via load_database_file().

• In this state, it is not valid for file type identification.

• Methods that require a loaded database (e.g., identify_file) will throw or return errors if called.

• is_open() returns true.

• is_database_loaded() returns false.

• is_valid() returns false.

3. Valid Magic

• The magic is valid if it is open and a magic database file has been successfully loaded.

• In this state, it can be used for file type identification.

• is_open() returns true.

• is_database_loaded() returns true.

• is_valid() returns true.

Libmagicxx CMake Package Variables

Below is a table describing the variables provided by Libmagicxx CMake package:

Variable	Description
MAGICXX_FOUND	Indicates if Libmagicxx was found by CMake.
MAGICXX_VERSION	The version of the installed Libmagicxx package.
MAGICXX_SHARED_LIB_AVAILABLE	Whether the shared library is available.
MAGICXX_STATIC_LIB_AVAILABLE	Whether the static library is available.
MAGICXX_INCLUDE_DIR	Path to the Libmagicxx include directory.
MAGICXX_LIB_DIR	Path to the Libmagicxx library directory.
MAGICXX_LICENSE_DIR	Path to the Libmagicxx license directory.
MAGICXX_DOC_DIR	Path to the Libmagicxx documentation directory.
MAGICXX_CMAKE_DIR	Path to the Libmagicxx CMake configuration directory.
MAGICXX_DEFAULT_DATABASE_DIR	Path to the default database directory of Libmagicxx.

Note: MAGICXX_DOC_DIR may be empty if the documentation is not installed.

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.