DOCSEARCHbyAlgolia
Submit Docs

Min-DevKit

repository·main·Indexed 42 days ago

https://github.com/cycling74/min-devkit

Tools, documentation, and reference implementations for creating Max packages using the modern Min-API. It provides a foundation for developers writing C++ externals for Max, including the min-api support files and min-lib building blocks for audio, video, and data processing.

Tokens
3.1K
Snippets
7
Records
20
Agent score
52%

What's inside Min-DevKit

  1. Overview of Hoedown Markdown Parser

    main

    Hoedown is a high-performance Markdown parser written in C (C99) that is a revived fork of Sundown. It is designed to be zero-dependency, standards-compliant (Markdown v1.0.0 and v1.0.3), and UTF-8 aware.

    Key characteristics include:

    • Performance: Optimized for speed; significantly faster than many native alternatives when used via language bindings.
    • Security: Extensively audited with protections against DOS attacks (stack overflows, out of memory, etc.).
    • Extensibility: The parser is decoupled from the renderer, allowing for custom renderers beyond the included (X)HTML implementation.
    • Extensions: Supports non-strict emphasis, fenced code blocks, tables, autolinks, and strikethrough.
    • Unicode Handling: Takes a conservative approach where punctuation and whitespace characters outside the U+007F codepoint are treated as normal in-word characters for word-boundary checks.

  2. Choose a development workflow for Min-DevKit

    main

    There are two primary ways to work with Min-DevKit:

    1. Launcher-based workflow: Open the Min-DevKit Launcher and use Max to generate new packages, add new objects to existing packages, and launch your IDE (Xcode or Visual Studio).
    2. Manual workflow: Use the source code directly from GitHub and follow the instructions in the repository's README to manage the technology stack yourself.

    Note: The following documentation in this repository pertains only to the Launcher-based workflow.

  3. Understand the Min-DevKit structure

    main

    The Min-DevKit is composed of three primary layers that provide the foundation for building Max packages using the Min-API:

    • min-devkit: An example package that demonstrates current best practices for package creation.
    • min-api: A directory containing all necessary support files to compile external objects written in modern C++. You should include this folder within your own package's source directory.
    • min-lib: A collection of building blocks, helper classes, and unit generators designed to assist in authoring C++ code for audio, video, and data processing.

  4. Install prerequisites for Min-DevKit

    main

    Before building externals, ensure your system meets the following requirements:

    Compilers

    • macOS: Xcode 10, 11, or 12.
    • Windows: Visual Studio 2017 or 2019 (it is recommended to install Git via the Visual Studio installer).

    Build Tools

    • CMake: Version 3.19 or higher must be installed.

  5. Install Hoedown

    main

    You can install Hoedown using one of the following methods:

    Using Make

    Run make to build Hoedown into a dynamic library. This also creates the hoedown and smartypants command-line executables.

    make

    Using CocoaPods

    Add the following line to your Podfile and run pod install:

    pod 'hoedown'

    Manual Integration

    Since Hoedown is a zero-dependency library composed of .c files and headers, you can manually add the files from the src directory directly into your project.

  6. Verify a new package installation by building and testing

    main

    After running the package creation script, follow these steps to ensure the scaffolding is correct and the environment is functional:

    1. Navigate to the build directory: cd <package_path>/build.
    2. Run CMake for your specific platform.
    3. Build the project (refer to the main README.md for platform-specific build commands).
    4. Run the unit tests (refer to the main README.md for test execution).
    5. Open Max and test the default foo.hello-world object using its help patcher to confirm successful integration.

  7. Run unit tests in Min-DevKit

    main

    You can verify your builds using ctest via the command line or by running individual test binaries.

    Using CTest

    Run these commands from within your build directory:

    • Debug builds: ctest -C Debug .
    • Release builds: ctest -C Release .

    Running individual tests

    Navigate to the tests directory and execute the test binary directly:

    • macOS: ./test_dcblocker_tilde -s
    • Windows: test_dcblocker_tilde.exe -s

    Using an IDE

    In Xcode or Visual Studio, you can run tests by selecting the RUN_TESTS target.

    # Example for a release build
ctest -C Release .

  8. Run unit tests for Min objects

    main

    Min-DevKit uses the Catch framework for unit testing. You can run tests using your IDE's debugger (Xcode or Visual Studio) or via the command line.

    To run tests via the command line, navigate to the tests directory and execute the test binary with the -s flag.

    Example (macOS):

    cd ..
cd tests
./[object_name]_test -s

    Example (Windows):

    cd ..
cd tests
[object_name]_test.exe -s
    # macOS example
./min.dcblocker_tilde_test -s

# Windows example
min.dcblocker_tilde_test.exe -s

  9. Submit a Pull Request to Min-DevKit

    main

    Contributions to the Min API and DevKit should be submitted via GitHub Pull Requests. To ensure your PR is considered, follow these requirements:

    • Description: Include a clear description of the intended changes.
    • Testing: The final commit of the PR must pass all tests on all platforms. While not required for every intermediate commit, the final state must be stable.
    • Commit Messages: Use clear, unambiguous messages. Link commits to GitHub issue numbers (e.g., include see #1974 in the message).
    • Test Coverage: Include appropriate tests covering reasonable permutations of the change and include baseline changes. Aim for 100% code coverage on all changed code.

  11. Manage Git submodules when committing changes

    main

    The Min-DevKit uses Git submodules (specifically source/min-api). When contributing, be aware of the following workflow constraints to avoid losing work or creating dangling references:

    Avoid Submodule Resetting

    If you make local changes inside source/min-api, they will work for local builds/tests. However, once you commit changes in the top-level Min-DevKit, the CMake scripts may automatically reset the submodule to the specific commit recorded in the host repository, potentially overwriting your local submodule changes. Refer to the HowTo-UpdateTheAPI.md guide to recover.

    Avoid Detached HEAD commits

    Submodules are often set to a specific commit rather than a branch head. Before committing, verify you are on a branch using git branch or git status. If you accidentally commit to a detached HEAD:

    1. Note the commit hashes using git log.
    2. Cherry-pick those commits onto the correct branch.

    Correct Push Order

    Crucial: You must push commits to the Min-API (the submodule) before pushing commits to Min-DevKit (the host/container). Pushing the host repository first will result in a dangling reference to a non-existent commit in the submodule.

  12. Build Min-DevKit on macOS

    main

    Follow these steps to generate and build the project using Xcode:

    1. Navigate to the cloned directory in your terminal.
    2. Create and enter a build directory:
      mkdir build && cd build
    3. Generate the Xcode project:
      cmake -G Xcode ..
    4. Build the project using CMake or via the Xcode GUI:
      cmake --build .

    Tips:

    • Use cmake --build . -j4 (replacing 4 with your core count) to speed up builds.
    • Apple Silicon (M1/M2) Fix: If you encounter a cannot be loaded due to system security policy error in Max, ad-hoc codesign your external:
      codesign --force --deep -s - myobject.mxo
    cmake -G Xcode ..
cmake --build .