From f7bd0049d071155cfa68876fa4b3eef5515c909c Mon Sep 17 00:00:00 2001 From: Adam Szmigin Date: Tue, 16 Dec 2025 23:50:35 +0000 Subject: [PATCH] Usage guide and contribution docs --- CONTRIBUTING.md | 61 +++++++++++++++++++++++++++++++++++ GUIDE.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 23 ++++++------- 3 files changed, 158 insertions(+), 11 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 GUIDE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1a701bd --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,61 @@ +Contributing to libdjinterop +============================ + +If you are interested in contributing to `libdjinterop`, thank you! + +The easiest way to contribute is to look at the +[issues list](https://github.com/xsco/libdjinterop/issues) and see if there is +anything that you might like to try. + +Although `libdjinterop` is a C++ library, there are usually both coding and +non-coding tasks available. All contributions are hugely appreciated! + +C++ Style Guide +--------------- + +C++ coding conventions in `libdjinterop` broadly follow the +[Core C++ Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) +from ISO C++. + +Furthermore, there is a [.clang-format](.clang-format) file in the repository, +and all code contributions should conform to this. + +Perhaps one day there will be more opinionated formatting/linting, or indeed +a pre-commit hook to enforce it. + +Unit Testing +------------ + +High unit test coverage is _strongly encouraged_ for all C++ code contributions. +It may become a mandatory requirement one day. + +External Dependencies +--------------------- + +Introducing any additional external dependencies into `libdjinterop` is a big +decision that requires proper consideration. The aim is for the library to be +built and compiled with minimal additional requirements, in order to make +wider adoption as easy as possible. + +For an external dependency to be considered, ideally it should be readily +available on all stable versions of each target operating system, as well as +be a stable and mature library. + +For dependencies that do not meet these criteria, another option is to 'vendor' +the dependencies into the codebase under the [ext/](ext) directory hierarchy. + +OS Compatibility +---------------- + +The library is expected to compile on: + +* Windows - all supported versions +* Linux: + * Ubuntu - all LTS versions + * Red Hat and friends - all supported versions + * Arch Linux +* macOS - all recent versions + +The biggest user of this library is undoubtedly the [Mixxx](https://mixxx.org) +open source DJ application. As such, it is a very sensible idea to ensure that +the library always compiles on the operating systems that Mixxx targets too. diff --git a/GUIDE.md b/GUIDE.md new file mode 100644 index 0000000..875ccc7 --- /dev/null +++ b/GUIDE.md @@ -0,0 +1,85 @@ +Guide to libdjinterop +===================== + +This documentation provides an introductory guide to the public API of +`libdjinterop`, and provides information on how to get started using it. + +High-level vs. Low-level APIs +----------------------------- + +The library offers so-called "high-level" and "low-level" APIs, which serve +different purposes. + +Low-level APIs +-------------- + +The low-level APIs provides a very thin wrapper over a specific DJ database +library format. A low-level API exposes all the peculiarities, details, and +expressivity of that format, and does not offer any abstractions beyond +presenting a C++ library interface. + +There are multiple low-level APIs, one for each type of DJ library format. +There can also be multiple low-level APIs to cover occasions where a library +undergoes a significant change to its schema (e.g. Engine 1.x and Engine 2.x +are distinct low-level APIs). + +Sometimes, a low-level API (or collection of them) offer utility functions that +help the end user translate from common concepts into encodings or types that +are specific to the low-level library format. An example could be calculating +the preferred size of a waveform for a given format. + +The current low-level APIs offered are listed below: + +| Low-level API | Include Path | +|---------------|-----------------------------------------------------| +| Engine 2.x | `#include ` | +| Engine 3.x | `#include ` | + +Note that there is no low-level API for Engine 1.x at present. This is because +when the library was first being written, Engine 1.x support was introduced +directly into the high-level API without a low-level companion. The low-level +API was developed with the introduction of Engine 2.x, and because the 1.x +library was effectively now deprecated, the effort was not undertaken to +backport the idea to 1.x. If a low-level API for Engine 1.x is important to +you, please consider contributing! + +High-level API +-------------- + +The library offers a high-level API as well, with a very different purpose to +that of the low-level APIs. Whereas low-level APIs simply expose an underlying +DJ library format in the form of a C++ API, the high-level API aims to: + +* Abstract over all format-specific aspects. +* Offer a uniform interface, regardless of the underlying DJ library format. +* Offer meaningful DJ library concepts, in the form of lightweight handles to + objects in the underlying DJ library, that can be read or updated. + +The primary concepts in the high-level API are: + +* _Database_, representing the overall DJ library. +* _Track_, representing a lightweight handle to a track in the library. +* _Track snapshot_, representing a collection of offline data read from a track + in the library. +* _Crate_, representing an unordered list of related tracks. +* _Playlist_, representing an ordered list of related tracks. + +Part of the challenge in developing `libdjinterop` is to ensure that the +high-level API appropriately abstracts over all the different ways that the +above concepts might be implemented in a real DJ library format. + +In reality, a DJ library that exists on disk is always of a specific format. +As such, in order to create a new library or load an existing library with the +intention of operating on it using the high-level API, it is always necessary +to start with format-specific functions to do so: + +| Library Type | Include Path | +|--------------|------------------------------------------| +| Engine | `#include ` | + + +Stable API/ABI +-------------- + +The library does not yet commit to offer either a stable API nor ABI. This +situation may change in the future as the library matures. diff --git a/README.md b/README.md index b2187aa..4951cd1 100644 --- a/README.md +++ b/README.md @@ -4,17 +4,11 @@ Overview `libdjinterop` is a C++ library that allows access to database formats used to store information about DJ record libraries. -This library currently supports: - -* Engine Library, as used on "Prime"-series DJ equipment. - -Documentation can be viewed on [GitHub Pages](https://xsco.github.io/libdjinterop/) - State of Support ================ -The library is currently in an early beta stage, and not all features are -implemented yet. It currently supports only the Engine Library format. +The library is currently in development, and not all features are implemented +yet. It currently supports only the Engine Library format. What is supported: @@ -29,7 +23,8 @@ What is supported: The library supports the following firmware and application versions: * Engine DJ OS from 1.0.3 to 4.3.3. - * Tested on Denon SC5000 and Numark Mixstream Pro. Other players (e.g. SC6000/M) may work, but this is currently untested. + * Tested on Denon SC5000 and Numark Mixstream Pro. Other players (e.g. + SC6000/M) may work, but this is currently untested. * Engine DJ Desktop (aka Engine Prime) from 1.0.1 to 4.3.0. What is not supported (yet): @@ -41,8 +36,14 @@ What is not supported (yet): How Do I Use It? ================ -The library is not ready for prime-time yet, but if you are willing to read -source code, example applications can be found in the `example` directory. +If you are new to the library, see the [introductory guide](GUIDE.md) for an +explanation of how the library is structured and how to get started. + +The [examples/](example) directory contains some small self-contained +applications that use the library. + +Detailed reference documentation for the public API can be viewed on +[GitHub Pages](https://xsco.github.io/libdjinterop/). How Do I Build It? ============================