Skip to content

Compile.md

Latest commit

 

History

History
70 lines (46 loc) · 6.44 KB

Compile.md

File metadata and controls

70 lines (46 loc) · 6.44 KB

Compiling Volume Control from Source (Xcode Guide)

Introduction: The simplest way to use Volume Control is to download the latest notarized release. This version is signed by the author, notarized by Apple, and should run on your Mac without any security warnings.

However, if you prefer to build the app yourself—for example, to make custom changes, verify the source code, or if you prefer to run an app signed with your own certificate—this guide provides step-by-step instructions to compile and sign Volume Control on your Mac using Xcode.

Compiling from source is also a reliable workaround if macOS security measures (Gatekeeper) ever prevent an official release from launching on your specific setup. Following these steps will allow you to run the app signed with your own Apple ID.

Prerequisites

  • macOS: A Mac running macOS Ventura (13) or newer (e.g. “Sequoia”).
  • Xcode: Installed from the App Store (or Apple’s developer site). Make sure Xcode is up-to-date and compatible with your macOS version.
  • Apple ID: An Apple ID configured in Xcode. You do not need a paid developer membership – a free Apple ID with a Personal Team is enough for code signing.
  • Git: (Optional) To clone the repository. macOS comes with Git (or Xcode’s Command Line Tools provide it). Alternatively, you can download the source as a ZIP from GitHub if you prefer.

Step-by-Step Compilation Instructions

  1. Clone the Volume Control repository. Open Terminal and run:

    git clone https://github.com/alberti42/Volume-Control.git

    This will download the project source code into a folder named Volume-Control (or you can use GitHub Desktop or download the ZIP from the GitHub page and extract it). For example, if you clone via Terminal, you should now have a Volume-Control directory containing files like Volume Control.xcodeproj.

  2. Configure your local signing settings. Before opening the project, create your local configuration file. In Terminal, run:

    cp LocalSigning.xcconfig.example LocalSigning.xcconfig

    Open LocalSigning.xcconfig in a text editor. You will update the DEVELOPMENT_TEAM and BUNDLE_ID_BASE in the following steps.

  3. Open the project in Xcode. Navigate to the cloned Volume-Control folder in Finder. You should see a file called Volume Control.xcodeproj – this is the Xcode project file. Double-click it to open the project in Xcode (you can also launch Xcode first and go to File > Open and select this file). This will load the Volume Control project in Xcode. You should see the project’s files and settings in Xcode’s interface.

    Volume Control Xcode project in Finder
    Finder window with Volume Control.xcodeproj selected, ready to be opened in Xcode.

  4. Add your Apple ID account to Xcode (if not already added). In Xcode, open Xcode > Settings (on macOS Ventura, Xcode’s preferences are labeled “Settings”; on older macOS it’s Xcode > Preferences). Go to the Accounts tab. If your Apple ID is not listed here, click the “+” button in the lower-left and choose “Apple ID”, then sign in with your Apple ID credentials. Once added, you should see your Apple ID in the list, and Xcode will display a Personal Team associated with it (usually with your name or email). Note the Team ID (a 10-character alphanumeric string) displayed next to your name; you will need this for the next step.

    Xcode Accounts with Personal Team
    Xcode Settings – Accounts tab, showing an Apple ID added and a Personal Team available for code signing.

  5. Update your local configuration. Now that you have your Team ID, open the LocalSigning.xcconfig file you created in Step 2 and:

    • Replace 0000000000 with your Team ID.
    • Change com.example.VolumeControl to a unique Bundle ID base (e.g., com.yourname.VolumeControl).

    Xcode will automatically pick up these changes and apply them to the Signing & Capabilities tab of the project.

  6. Verify the settings in Xcode. Back in the Xcode project, click on the project name “Volume Control” in the Project Navigator (the left sidebar). Ensure the “Volume Control” target is selected. Click on the Signing & Capabilities tab. You should see that the Team and Bundle Identifier now reflect the values you entered in the .xcconfig file. Keep “Automatically manage signing” checked.

    Xcode Signing & Capabilities with Team and Bundle ID
    In Xcode’s Signing & Capabilities for the Volume Control target: the settings are now managed via LocalSigning.xcconfig.

  7. Build the project to verify everything is set up. Now that signing is configured, build the app. Go to Product > Build (or press ⌘B) to compile Volume Control. The build should succeed (you’ll see a “Build Succeeded” message in the status bar) and Xcode will generate the app binary.

  8. Archive the app for release. After a successful build, go to Product > Archive to create a release build.

    Xcode Product > Archive menu
    In Xcode, go to Product > Archive to create a release build of the app.

  9. Locate the built app. Once archived, the Organizer window will open. Choose “Distribute” or “Export” and follow the prompts to extract the .app file. Alternatively, right-click on the archive in Finder → Show Package Contents → go to Products/Applications/.

  10. Install and run the app. Drag the Volume Control.app to your Applications folder. Launch it — macOS should trust it since it's now signed with your own certificate.

Note: Automatic updates via Sparkle won't work if the bundle identifier is changed. You'll need to manually check the GitHub repository for updates.

Troubleshooting

  • Signing errors? Ensure you've:
    • Added your Apple ID in Xcode → Settings → Accounts.
    • Correctly copied your Team ID into LocalSigning.xcconfig.
    • Changed the bundle ID base to something unique in LocalSigning.xcconfig.
  • Archive grayed out? Ensure your scheme is selected and the destination is “My Mac”.