Reference#

JSON configuration overview#

This is an auto-generated overview of all the possible settings each menuinst JSON file can include. Note that each platform sub-dict can override top-level values if required. See Schema below for more details.

{
  "id_": "https://schemas.conda.io/menuinst-1.schema.json",
  "schema_": "https://json-schema.org/draft-07/schema",
  "menu_name": "REQUIRED",
  "menu_items": [
    {
      "name": "REQUIRED",
      "description": "REQUIRED",
      "command": [
        "REQUIRED"
      ],
      "icon": null,
      "precommand": null,
      "precreate": null,
      "working_dir": null,
      "activate": true,
      "terminal": false,
      "platforms": {
        "linux": {
          "Categories": null,
          "DBusActivatable": null,
          "GenericName": null,
          "Hidden": null,
          "Implements": null,
          "Keywords": null,
          "MimeType": null,
          "NoDisplay": null,
          "NotShowIn": null,
          "OnlyShowIn": null,
          "PrefersNonDefaultGPU": null,
          "SingleMainWindow": null,
          "StartupNotify": null,
          "StartupWMClass": null,
          "TryExec": null,
          "glob_patterns": null
        },
        "osx": {
          "CFBundleDisplayName": null,
          "CFBundleIdentifier": null,
          "CFBundleName": null,
          "CFBundleSpokenName": null,
          "CFBundleVersion": null,
          "CFBundleURLTypes": null,
          "CFBundleDocumentTypes": null,
          "LSApplicationCategoryType": null,
          "LSBackgroundOnly": null,
          "LSEnvironment": null,
          "LSMinimumSystemVersion": null,
          "LSMultipleInstancesProhibited": null,
          "LSRequiresNativeExecution": null,
          "NSSupportsAutomaticGraphicsSwitching": null,
          "UTExportedTypeDeclarations": null,
          "UTImportedTypeDeclarations": null,
          "entitlements": null,
          "link_in_bundle": null,
          "event_handler": null
        },
        "win": {
          "desktop": true,
          "quicklaunch": false,
          "terminal_profile": null,
          "url_protocols": null,
          "file_extensions": null,
          "app_user_model_id": null
        }
      }
    }
  ]
}

Configuration schema#

Metadata required to create menu items across operating systems with menuinst.

field $id: Literal['https://schemas.conda.io/menuinst-1.schema.json'] [Required] (name 'id_')#

Version of the menuinst schema.

field $schema: Literal['https://json-schema.org/draft-07/schema'] [Required] (name 'schema_')#

Standard of the JSON schema we adhere to.

Name for the category containing the items specified in menu_items.

Constraints:

  • minLength = 1

List of menu entries to create across main desktop systems.

Constraints:

  • minItems = 1

Instructions to create a menu item across operating systems.

The name of the menu item. Can be a dictionary if the name depends on installation parameters. See MenuItemNameDict for details.

A longer description of the menu item. Shown on popup messages.

Command to run with the menu item, expressed as a list of strings where each string is an argument.

Constraints:

  • minItems = 1

Path to the file representing or containing the icon.

Constraints:

  • minLength = 1

(Simple, preferrably single-line) logic to run before the command is run. Runs before the environment is activated, if that applies.

Constraints:

  • minLength = 1

(Simple, preferrably single-line) logic to run before the shortcut is created.

Constraints:

  • minLength = 1

Working directory for the running process. Defaults to user directory on each platform.

Constraints:

  • minLength = 1

Whether to activate the target environment before running command.

Whether run the program in a terminal/console or not. On Windows, it only has an effect if activate is true. On MacOS, the application will ignore command-line arguments.

Platform-specific options. Presence of a platform field enables menu items in that platform.

Variable menu item name. Use this dictionary if the menu item name depends on installation parameters such as the target environment.

Name when target environment is the base environment.

Constraints:

  • minLength = 1

Name when target environment is not the base environment.

Constraints:

  • minLength = 1

Platform specific options.

Note each of these fields supports the same keys as the top-level MenuItem (sans platforms itself), in case overrides are needed.

Options for Linux. See Linux model for details.

Options for macOS. See MacOS model for details.

Options for Windows. See Windows model for details.

Linux-specific instructions.

Check the Desktop entry specification for more details.

Categories in which the entry should be shown in a menu. “See ‘Registered categories’ in the Menu Spec.

A boolean value specifying if D-Bus activation is supported for this application.

Generic name of the application; e.g. if the name is ‘conda’, this would be ‘Package Manager’.

Disable shortcut, signaling a missing resource.

List of supported interfaces. See ‘Interfaces’ in Desktop Entry Spec.

Additional terms to describe this shortcut to aid in searching.

The MIME type(s) supported by this application. Note this includes file types and URL protocols. For URL protocols, use x-scheme-handler/your-protocol-here. For example, if you want to register menuinst:, you would include x-scheme-handler/menuinst.

Do not show this item in the menu. Useful to associate MIME types and other registrations, without having an actual clickable item. Not to be confused with ‘Hidden’.

Desktop environments that should NOT display this item. It’ll check against $XDG_CURRENT_DESKTOP.”

Desktop environments that should display this item. It’ll check against $XDG_CURRENT_DESKTOP.

Hint that the app prefers to be run on a more powerful discrete GPU if available.

Do not show the ‘New Window’ option in the app’s context menu.

Advanced. See Startup Notification spec.

Advanced. See Startup Notification spec.

Filename or absolute path to an executable file on disk used to determine if the program is actually installed and can be run. If the test fails, the shortcut might be ignored / hidden.

Map of custom MIME types to their corresponding glob patterns (e.g. *.txt). Only needed if you define custom MIME types in MimeType.

Mac-specific instructions. Check these URLs for more info:

Display name of the bundle, visible to users and used by Siri. If not provided, ‘menuinst’ will use the ‘name’ field.

Document types supported by this app. Requires setting event_handler too. Requires macOS 10.14.4 or above.

Unique identifier for the shortcut. Typically uses a reverse-DNS format. If not provided, ‘menuinst’ will generate one from the ‘name’ field.

Constraints:

  • pattern = ^[A-z0-9-.]+$

Short name of the bundle. May be used if CFBundleDisplayName is absent. If not provided, ‘menuinst’ will generate one from the ‘name’ field.

Constraints:

  • maxLength = 16

Suitable replacement for text-to-speech operations on the app. For example, ‘my app one two three’ instead of ‘MyApp123’.

URL types supported by this app. Requires setting event_handler too. Note this feature requires macOS 10.14.4 or above.

Build version number for the bundle. In the context of ‘menuinst’ this can be used to signal a new version of the menu item for the same application version.

Constraints:

  • pattern = ^S+$

The App Store uses this string to determine the appropriate categorization.

Constraints:

  • pattern = ^public.app-category.S+$

Specifies whether this app runs only in the background.

Minimum version of macOS required for this app to run, as x.y.z. For example, for macOS v10.4 and later, use 10.4.0.

Constraints:

  • pattern = ^d+.d+.d+$

Whether an app is prohibited from running simultaneously in multiple user sessions.

If true, prevent a universal binary from being run under Rosetta emulation on an Intel-based Mac.

If true, allows an OpenGL app to utilize the integrated GPU.

The uniform type identifiers owned and exported by the app.

The uniform type identifiers inherently supported, but not owned, by the app.

List of permissions to request for the launched application. See the entitlements docs for a full list of possible values.

Required shell script logic to handle opened URL payloads. Note this feature requires macOS 10.14.4 or above.

Constraints:

  • minLength = 1

Paths that should be symlinked into the shortcut app bundle. It takes a mapping of source to destination paths. Destination paths must be relative. Placeholder {{ MENU_ITEM_LOCATION }} can be useful.

Describes a document type associated with the app.

This key specifies the app’s role with respect to the type.

Determines how Launch Services ranks this app among the apps that declare themselves editors or viewers of files of this type.

List of UTI strings defining a supported file type; e.g. for PNG files, use ‘public.png’. See UTI Reference for more info about the system-defined UTIs. Custom UTIs can be defined via ‘UTExportedTypeDeclarations’. UTIs defined by other apps (not the system) need to be imported via ‘UTImportedTypeDeclarations’.

See Fun with UTIs for more info.

Describes a URL scheme associated with the app.

This key specifies the app’s role with respect to the URL.

The Uniform Type Identifier types that this type conforms to.

A description for this type.

The bundle icon resource to associate with this type.

The Uniform Type Identifier to assign to this type.

The webpage for a reference document that describes this type.

A dictionary defining one or more equivalent type identifiers.

Windows-specific instructions. You can override global keys here if needed

Whether to create a desktop icon in addition to the Start Menu item.

DEPRECATED. Whether to create a quick launch icon in addition to the Start Menu item.

Name of the Windows Terminal profile to create. This name must be unique across multiple installations because menuinst will overwrite Terminal profiles with the same name.

Constraints:

  • minLength = 1

URL protocols that will be associated with this program.

File extensions that will be associated with this program.

Identifier used in Windows 7 and above to associate processes, files and windows with a particular application. If your shortcut produces duplicated icons, you need to define this field. If not set, it will default to Menuinst.<name>.

See AppUserModelID docs for more information on the required string format.

Constraints:

  • maxLength = 128

  • pattern = S+.S+

Placeholders#

The JSON configuration files support several placeholders if surrounded with spaced double curly braces: {{ variable }}.

Note these are not Jinja templates! No logic, filters, methods or anything. Just the placeholder name!

General placeholders#

Name

Value

BASE_PREFIX

Path to the base Python location. In conda terms, this is the base environment

DISTRIBUTION_NAME

Name of the base prefix directory; e.g. if BASE_PREFIX is /opt/my-project, this is my-project.

PREFIX

Path to the target Python location. In conda terms, this is the path to the environment that contains the JSON file for this menu item. In some cases, it might be the same as BASE_PREFIX.

ENV_NAME

Same as DISTRIBUTION_NAME, but for PREFIX.

PYTHON

Path to the python executable in PREFIX.

BASE_PYTHON

Path to the python executable in BASE_PREFIX.

MENU_DIR

Path to the Menu directory in PREFIX.

MENU_ITEM_LOCATION

Path to the main menu item artifact once installed. On Linux, this is the path to the .desktop file, on macOS it is the path to the .app directory, and on Windows it is the path to the Start Menu .lnk file.

BIN_DIR

Path to the bin (Unix) or Library/bin (Windows) directories in PREFIX.

PY_VER

Python major.minor version in PREFIX.

SP_DIR

Path to Python’s site-packages directory in PREFIX.

HOME

Path to the user directory (~).

ICON_EXT

Extension of the icon file expected by each platform. png in Linux, icns in macOS, and ico in Windows. Note the dot is not included.

macOS placeholders#

Name

Value

PYTHONAPP

Path to the python executable installed in PREFIX, assuming the python.app conda package is installed. Equivalent to {{ PREFIX }}/python.app/Contents/MacOS/python.

Windows placeholders#

Name

Value

SCRIPTS_DIR

Path to the Scripts directory in PREFIX.

BASE_PYTHONW

Path to the pythonw.exe executable in BASE_PREFIX.

PYTHONW

Path to the pythonw.exe executable in PREFIX.