Documentation Modification Suggestions

[satbirkira]

Hey there. I'm going through the process of moving a plugin to pample juce. I thought I would try to contribute by going through some problems as I face them in hopes to help with the documentation!

1. BinaryData

I was just wondering if you could explicitly write on this page that anything put in the /assets/ folder will be used to create a BinaryData.h / BinaryData.cpp like projucer used to generated for you. And also that the folder is not shown on the xcode project navigator but you should use finder to add the files. Lastly, a warning not to put files in here that are not needed for the plugin as it will be added as binary data to the plugin (maybe the pamplejuce.png should be moved to another folder)!

2. No CMAKE_CXX_COMPILER error

When I tried to run "cmake -B Builds -G Xcode" it failed and said

"No CMAKE_CXX_COMPILER could be found." "No CMAKE_C_COMPILER could be found."

Even though the OS recognizes they exist and where.

I found this command did the trick: sudo xcode-select --reset

3. Common <JuceHeader.h> replacements:

Plugin Processor
target_link_libraries addition: juce_audio_processors
#include <juce_audio_processors/juce_audio_processors.h>

Plugin Editor / GUI Components
target_link_libraries addition: juce_gui_basics, juce_gui_extra
#include <juce_gui_basics/juce_gui_basics.h>
#include <juce_gui_extra/juce_gui_extra.h>

juce::PropertiesFile
target_link_libraries addition: juce_data_structures
#include <juce_data_structures/juce_data_structures.h>

juce::dsp
target_link_libraries addition: juce_dsp
#include <juce_dsp/juce_dsp.h>

juce::AudioBuffer
target_link_libraries addition: juce_audio_basics
#include <juce_audio_basics/juce_audio_basics.h>

juce::OnlineUnlockStatus
target_link_libraries addition: juce_product_unlocking
#include <juce_product_unlocking/juce_product_unlocking.h>

juce::Thread
target_link_libraries addition: juce_events
#include <juce_events/juce_events.h>

juce::Logger
target_link_libraries addition: juce_core
#include <juce_core/juce_core.h>

BinaryData::
target_link_libraries addition: none
#include "BinaryData.h"

4. Make sure your Plugin Processor has this header at the top

#if (MSVC)

#include "ipps.h"

#endif

5. How to -o3 optimized build on debug builds

Still figuring out how to do this!

6. In test_helpers.h you need to replace "PluginProcessor" with the name of your processor class.

[[maybe_unused]] static void runWithinPluginEditor (const std::function<void (PluginProcessor& plugin)>& testCode)
{
    PluginProcessor plugin;
    const auto editor = plugin.createEditorIfNeeded();

    testCode (plugin);

    plugin.editorBeingDeleted (editor);
    delete editor;
}

7. In PluginBasics.cpp you also need to replace "PluginProcessor" with the name of your processor class.

TEST_CASE ("Plugin instance", "[instance]")
{
    PluginProcessor testPlugin;

    SECTION ("name")
    {
        CHECK_THAT (testPlugin.getName().toStdString(),
            Catch::Matchers::Equals ("My Plugin Name"));
    }
}

8. In Benchmarks.cpp you also need to replace "PluginProcessor" with the name of your processor class.

9. You can use this script to test the full build locally before spending CI minutes (and quickly figure out why the CI build failed)

test-ci-local.sh

#!/bin/bash

# How to test the CI/CD build phase locally on macOS:
# 1. Run `chmod +x test-ci-local.sh` to make the script executable
# 2. brew install ninja
# 3. Run `./test-ci-local.sh`

# Define variables
BUILD_DIR="Builds"
BUILD_TYPE="Release"

# Remove the entire Builds directory to start fresh
rm -rf "$BUILD_DIR"

# Create build directory
mkdir -p "$BUILD_DIR"

# Configure with CMake and Ninja generator, suppressing warnings
cmake -B "$BUILD_DIR" \
      -G Ninja \
      -DCMAKE_BUILD_TYPE="$BUILD_TYPE" \
      -DCMAKE_C_FLAGS="-w" \
      -DCMAKE_CXX_FLAGS="-w" \
      .

# Build the project, showing only progress and errors
cmake --build "$BUILD_DIR" --config "$BUILD_TYPE" --parallel 4 --

# Check if the build succeeded
if [ $? -eq 0 ]; then
    # Run tests and benchmarks only if the build was successful
    "$BUILD_DIR"/Tests
    "$BUILD_DIR"/Benchmarks
else
    echo "Build failed. Tests and Benchmarks will not run."
    exit 1
fi

10. Generating .icns from figma

Insteading of manually exporting and making the file yourself, you can use this tool: https://www.figma.com/community/plugin/742318143106037364/icns-ico-generator

11. AU3 path exists but no mention of packaging

echo "AUV3_PATH=$ARTIFACTS_PATH/AUv3/${{ env.PRODUCT_NAME }}.appex" >> $GITHUB_ENV

This is in the workflow, but it doesn't seem to be used anywhere. It's a bit confusing because the default cmake has this:

set(FORMATS Standalone AU VST3 AUv3)

So I guess we make it, build it, but never package it?

12. Missing step in code sign azure

In "Step 4: Create “App Registration” user credentials", after giving it a name, there are some options.

Mention which to choose here.

13. Label AZURE_ENDPOINT and AZURE_CODE_SIGNING_NAME like other secrets in documentation

14 Mention to choose "User, group, or service principal", not Managed identity?

15 Some screenshots for the personal identity part

The dropdown:

Action required:

**The Action Page **

The partner

When it's done

Now scan it, the QR code is below this message:

**Note: The scan QR code is the icon in the top right corner **

Note2: Your identity will expire when your government issued card does (ex drivers license expires). Might be a good idea to message the code signing team if this invalidates the identity and you gatta do this all again

Last step: AZURE_CERT_PROFILE_NAME

16 Number of cores selected incorrect

For private repos, it's not four.

17 The dmg.json background.png image should be 72x72 DPI, the [email protected] should be 144x144DPI. Export figma 2x scale will do this for you.

[sudara]

This is all great stuff, thank you! I will take a deeper look when I'm combing through documentation again.

[7sharp9]

@satbirkira Are you using test-ci-local.sh to test on different systems like mac/windows?