{"id":14006773,"url":"https://github.com/hraban/mac-app-util","last_synced_at":"2025-04-12T21:33:56.923Z","repository":{"id":204792128,"uuid":"712672551","full_name":"hraban/mac-app-util","owner":"hraban","description":"Fix .app programs installed by Nix on Mac","archived":false,"fork":false,"pushed_at":"2025-03-16T20:50:00.000Z","size":59,"stargazers_count":279,"open_issues_count":9,"forks_count":13,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-04T07:20:30.499Z","etag":null,"topics":["apple","common-lisp","flakes","macos","nix","plist","plist-files","plutil"],"latest_commit_sha":null,"homepage":"","language":"Common Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hraban.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-01T00:22:26.000Z","updated_at":"2025-04-01T04:05:57.000Z","dependencies_parsed_at":"2023-11-01T05:28:51.789Z","dependency_job_id":"a22997e1-e21f-4e03-8954-f038977c347a","html_url":"https://github.com/hraban/mac-app-util","commit_stats":{"total_commits":48,"total_committers":1,"mean_commits":48.0,"dds":0.0,"last_synced_commit":"4f48e20f25a620c3d4ef658bb3804c849d46cc93"},"previous_names":["hraban/app-plist-copy","hraban/plist-copy","hraban/mac-app-util"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hraban%2Fmac-app-util","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hraban%2Fmac-app-util/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hraban%2Fmac-app-util/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hraban%2Fmac-app-util/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hraban","download_url":"https://codeload.github.com/hraban/mac-app-util/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248636844,"owners_count":21137527,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple","common-lisp","flakes","macos","nix","plist","plist-files","plutil"],"created_at":"2024-08-10T10:01:37.866Z","updated_at":"2025-04-12T21:33:56.897Z","avatar_url":"https://github.com/hraban.png","language":"Common Lisp","readme":"* (Nix) Utilities for Mac App launchers\n\nThis is a [[https://nixos.org][Nix]] module for Macintosh computers (“darwin”) which fixes a few common problems encountered by users of Nix on Macs:\n\n- Launching .app programs from Spotlight\n- Pinning a .app in the Dock, even across Nix updates\n\nNow you can launch Nix-installed apps using only your keyboard, using @@html:\u003ckbd\u003e@@⌘ space@@html:\u003c/kbd\u003e@@.\n\nYou can also use it to create .app wrappers for non-.app programs, aka stand-alone binary programs, aka non-bundle programs.\n\n** How to use\n\nIt works in [[https://github.com/nix-community/home-manager][home-manager]] and [[https://github.com/LnL7/nix-darwin][nix-darwin]] by providing a module for both.  You just need to load the module, nothing else, and it will automatically run every time you =switch= your config.\n\nHome-manager and nix-darwin aren’t either-or: you can have both, and you can install .app bundles on your mac through both (some user specific using home-manager, some system wide using nix-darwin).  In that case you’d want to load both the nix-darwin module, and the home-manager module at the same time in their respective configurations.\n\n*** Flakes, just home-manager\n\nOnly using home-manager, no nix-darwin (yet)? You can import the home-manager module directly:\n\n#+begin_src nix\n{\n  description = \"Minimal Flake for macOS with home-manager and mac-app-util\";\n\n  inputs = {\n    mac-app-util.url = \"github:hraban/mac-app-util\";\n  };\n\n  outputs = { self, nixpkgs, home-manager, mac-app-util, ... }: let\n    username = \"jdoe\";\n    system = \"aarch64-darwin\";\n  in {\n    homeConfigurations.${username} = home-manager.lib.homeManagerConfiguration {\n      pkgs = import nixpkgs { inherit system; config.allowUnfree = true; };\n      modules = [\n        mac-app-util.homeManagerModules.default\n        ({ pkgs, ... }: {\n          home = {\n            inherit username;\n            homeDirectory = \"/Users/${username}\";\n            # This is where you would install any programs as usual:\n            packages = with pkgs; [\n              ripgrep\n              vim\n\n              # What mac-app-util does for you, is that you can also just\n              # install derivations here which have a `/Applications/`\n              # directory, and it will be available in Spotlight and in your App\n              # Launcher, no further configuration needed:\n              vscode\n              iterm2\n            ];\n            stateVersion = \"24.05\";\n          };\n        })\n      ];\n    };\n  };\n}\n#+end_src\n\n*** Flakes, nix-darwin (with or without home-manager)\n\n#+begin_src nix\n{\n  inputs = {\n    #...\n    mac-app-util.url = \"github:hraban/mac-app-util\";\n    #...\n  };\n\n  outputs = {\n    nix-darwin\n    , home-manager\n    , mac-app-util\n    , ...\n  }: {\n    darwinConfigurations = {\n      MyHost = nix-darwin.lib.darwinSystem {\n        # ...\n\n        modules = [\n          mac-app-util.darwinModules.default\n\n          # And if you also use home manager:\n          home-manager.darwinModules.home-manager\n          (\n            { pkgs, config, inputs, ... }:\n            {\n              # To enable it for all users:\n              home-manager.sharedModules = [\n                mac-app-util.homeManagerModules.default\n              ];\n\n              # Or to enable it for a single user only:\n              home-manager.users.foobar.imports = [\n                #...\n                mac-app-util.homeManagerModules.default\n              ];\n            }\n          )\n\n        ];\n      };\n    };\n  };\n}\n#+end_src\n\n*** Non-flakes, aka “channels”\n\nThis is similar to the above. What will be different is the “plumbing”, i.e. how to get a reference to this app’s derivation. Here’s how:\n\n#+begin_src nix\nlet\n  mac-app-util-src = builtins.fetchTarball \"https://github.com/hraban/mac-app-util/archive/master.tar.gz\";\n  # I advise using the long form with a pinned hash instead\n  mac-app-util-src = builtins.fetchTarball {\n    url = \"https://github.com/hraban/mac-app-util/archive/abcdef123456abcdef123456.tar.gz\";\n    # Run it once, lift the hash from the error, paste it here and run again\n    sha256 = \"\";\n  };\n  mac-app-util = import mac-app-util-src {};\nin\n\n# Now you have either the program as a derivation itself:\nmac-app-util.default\n\n# Or the home manager module:\nmac-app-util.homeManagerModules.default\n\n# Or darwin:\nmac-app-util.darwinModules.default\n#+end_src\n\nExample:\n\n#+begin_src nix\n{ config, pkgs, ... }:\n\nlet\n  mac-app-util-src = builtins.fetchTarball \"https://github.com/hraban/mac-app-util/archive/master.tar.gz\";\n  mac-app-util = import mac-app-util-src {};\nin\n\n{\n  home = {\n    username = \"jdoe\";\n    homeDirectory = \"/Users/jdoe\";\n    stateVersion = \"24.05\";\n    packages = with pkgs; [\n      iterm2\n    ];\n  };\n  programs.home-manager.enable = true;\n  imports = [\n    mac-app-util.homeManagerModules.default\n  ];\n}\n#+end_src\n\n** Commands\n\nAt the core of this project is a (Nix-agnostic) program that can:\n\n- =mktrampoline= :: Create a “trampoline” launcher app\n- =sync-dock= :: Update persistent apps in the Dock\n- =sync-trampolines= :: Create a directory with trampolines to all your apps\n\n** mktrampoline\n\nThis creates a “trampoline” launcher app which is a simple wrapper application that just launches your actual application.\n\n#+begin_src shell\n$ nix run github:hraban/mac-app-util -- mktrampoline /path/to/MyApp.app /Applications/MyApp.app\n#+end_src\n\nIntuitively, you would either fully copy \u0026 paste the original .app, or create a symlink or “alias”; all of those solutions have different problems and they don’t get indexed by Spotlight properly.\n\nThis trampoline script is indexed by Spotlight and by Launchpad, so you can keep launching your apps using =⌘ SPC \u003cappname\u003e ⏎=\n\nYou can also wrap non-app stand-alone binaries with this. For example:\n\n#+begin_src shell\n$ nix run github:hraban/mac-app-util -- mktrampoline \"$(which darktable)\" ~/Applications/Darktable.app\n#+end_src\n\nDarktable is a photo editor available on Mac but without a .app bundle in the derivation. It’s just a stand-alone binary. Using mktrampoline, you can make it launchable from Spotlight.\n\nSee https://github.com/nix-community/home-manager/issues/1341\n\n** sync-dock\n\nWhen you have an app in your Dock which doesn’t live in =/Applications/..=, it can get stale: e.g. your app at =/foo/v1/Foo.app= gets replaced by =/foo/v2/Foo.app=. To automatically update the Dock to the new location of Foo, execute:\n\n#+begin_src shell\n$ nix run github:hraban/mac-app-util -- sync-dock Foo.app\n#+end_src\n\nIt will find an old persistent item by the name of \"Foo\" and update it to the new location.\n\nN.B.: This is currently limited only to Nix apps, but actually it could work for anything. I’ve just kept it conservative to be on the safe side.\n\n** sync-trampolines\n\nCombines =mktrampoline= and =sync-dock= to create a fresh directory with a fresh trampoline for every source app. E.g.:\n\n#+begin_src shell\n$ nix run github:hraban/mac-app-util -- sync-trampolines ~/special/apps/ ~/Applications/Special/\n#+end_src\n\nWill create a fresh directory (=~/Applications/Special=), deleting if it already existed. In that directory it will create a trampoline app for every single =*.app= file it finds in =~/special/apps/=.\n\nThis helps register apps from outside of your =~/Applications= directory with Spotlight and the Launchpad.\n\n* License\n\nmac-app-util - Manage Mac App launchers\nCopyright © 2023–2024  Hraban Luyat\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU Affero General Public License as published\nby the Free Software Foundation, version 3 of the License.\n\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU Affero General Public License for more details.\n\nYou should have received a copy of the GNU Affero General Public License\nalong with this program.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n\n","funding_links":[],"categories":["HarmonyOS","Common Lisp"],"sub_categories":["Windows Manager"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhraban%2Fmac-app-util","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhraban%2Fmac-app-util","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhraban%2Fmac-app-util/lists"}