🛠️ xcodebuild.nvim

A plugin designed to let you migrate your app development from Xcode to Neovim. It provides all essential actions for development including building, debugging, and testing.

✨ Features

• [x] Support for iOS, iPadOS, watchOS, tvOS, visionOS, and macOS.
• [x] Project-based configuration.
• [x] Project Manager to deal with project files without using Xcode.
• [x] Test Explorer to visually present a tree with all tests and results.
• [x] Built using official command line tools like xcodebuild and xcrun simctl.
• [x] Actions to build, run, debug, and test apps on simulators and physical devices.
• [x] Buffer integration with test results (code coverage, success & failure marks, duration, extra diagnostics).
• [x] Code coverage report with customizable levels.
• [x] Advanced log parser to detect all errors, warnings, and failing tests.
• x, neo-tree, and oil.nvim integration that automatically reflects all file tree operations and updates Xcode project.
• x integration to let you easily build, run, and debug apps.
• x integration to show app logs in the console window.
• x integration to show selected device, test plan, and other project settings.
• x integration to present diff views for failing snapshot tests.
• x integration to show test results for tests written using Quick framework.
• [x] Auto-detection of the target membership for new files.
• [x] Picker with all available plugin actions.
• [x] Highly customizable (many config options, auto commands, highlights, and user commands).

🌳 File Tree Integration

Xcodebuild.nvim is integrated with nvim-tree, neo-tree, and oil.nvim to let you manage your project and files in a convenient way.

Every change in the file tree presented by these plugins will be automatically reflected in the Xcode project file.

Additionally, the Project Manager will try predicting targets for newly created files based on their location. If you prefer to select targets manually, you can always disable it in the configuration using integrations.nvim_tree.guess_target or integrations.oil_nvim.guess_target.

https://github.com/wojciech-kulik/xcodebuild.nvim/assets/3128467/ed7d2d2e-eaa4-44ea-a1e6-0027ace4fb97

⚡️ Requirements

Neovim environment

• Neovim 0.9.5+
• telescope.nvim to present pickers.
• nui.nvim to present floating code coverage report.
• nvim-tree, neo-tree, or oil.nvim to visually manage your project files.
• nvim-dap and nvim-dap-ui to debug apps.
• nvim-treesitter + Swift parser to show test results for tests written using Quick framework.

External tools

• xcbeautify to format Xcode logs (you can set a different tool or disable formatting in the config).
• Xcodeproj to manage project files within Neovim.
• Ruby to use Xcodeproj gem.
• pymobiledevice3 to debug on physical devices and/or run apps on devices below iOS 17.
• xcode-build-server to make LSP work properly with xcodeproj/xcworkspace.
• codelldb to debug applications.
• Xcode to build, run, and test apps. Make sure that xcodebuild and xcrun simctl work correctly. Tested with Xcode 15.

Availability of features

🔐 - requires passwordless sudo permission for tools/remote_debugger script (see below).

🛠️ - available if pymobiledevice3 is installed.

🪲 - available while debugging.

📦 Installation

Install the plugin using your preferred package manager.

💤 lazy.nvim

return {
  "wojciech-kulik/xcodebuild.nvim",
  dependencies = {
    "nvim-telescope/telescope.nvim",
    "MunifTanjim/nui.nvim",
    "nvim-tree/nvim-tree.lua", -- (optional) to manage project files
    "stevearc/oil.nvim", -- (optional) to manage project files
    "nvim-treesitter/nvim-treesitter", -- (optional) for Quick tests support (required Swift parser)
  },
  config = function()
    require("xcodebuild").setup({
        -- put some options here or leave it empty to use default settings
    })
  end,
}

Install external tools:

brew install xcode-build-server
brew install xcbeautify
brew install ruby
brew install pipx
gem install xcodeproj
pipx install pymobiledevice3

To quickly install all required tools you can run:

cd ~/.local/share/nvim/lazy/xcodebuild.nvim
make install

[!TIP] Make sure to check out Tips & Tricks!

You will find there a collection of useful tips & tricks for development in Neovim.

📱 Setup Neovim For iOS Development

I wrote an article that gathers all the steps required to set up Neovim from scratch to develop iOS and macOS apps:

The Complete Guide To iOS & macOS Development In Neovim

You can also check out the sample Neovim configuration that I prepared for iOS development: ios-dev-starter-nvim

🚀 Usage

Make sure to open your project's root directory and run XcodebuildSetup to configure it. The plugin needs several information like project file, scheme, config, device, and test plan to be able to run commands.

Remember, that all the information are available in the help :h xcodebuild. Every function is documented and described both in the help and in the code.

🔧 Commands

⌘ Sample Key Bindings

vim.keymap.set("n", "<leader>X", "<cmd>XcodebuildPicker<cr>", { desc = "Show Xcodebuild Actions" })
vim.keymap.set("n", "<leader>xf", "<cmd>XcodebuildProjectManager<cr>", { desc = "Show Project Manager Actions" })

vim.keymap.set("n", "<leader>xb", "<cmd>XcodebuildBuild<cr>", { desc = "Build Project" })
vim.keymap.set("n", "<leader>xB", "<cmd>XcodebuildBuildForTesting<cr>", { desc = "Build For Testing" })
vim.keymap.set("n", "<leader>xr", "<cmd>XcodebuildBuildRun<cr>", { desc = "Build & Run Project" })

vim.keymap.set("n", "<leader>xt", "<cmd>XcodebuildTest<cr>", { desc = "Run Tests" })
vim.keymap.set("v", "<leader>xt", "<cmd>XcodebuildTestSelected<cr>", { desc = "Run Selected Tests" })
vim.keymap.set("n", "<leader>xT", "<cmd>XcodebuildTestClass<cr>", { desc = "Run Current Test Class" })
vim.keymap.set("n", "<leader>x.", "<cmd>XcodebuildTestRepeat<cr>", { desc = "Repeat Last Test Run" })

vim.keymap.set("n", "<leader>xl", "<cmd>XcodebuildToggleLogs<cr>", { desc = "Toggle Xcodebuild Logs" })
vim.keymap.set("n", "<leader>xc", "<cmd>XcodebuildToggleCodeCoverage<cr>", { desc = "Toggle Code Coverage" })
vim.keymap.set("n", "<leader>xC", "<cmd>XcodebuildShowCodeCoverageReport<cr>", { desc = "Show Code Coverage Report" })
vim.keymap.set("n", "<leader>xe", "<cmd>XcodebuildTestExplorerToggle<cr>", { desc = "Toggle Test Explorer" })
vim.keymap.set("n", "<leader>xs", "<cmd>XcodebuildFailingSnapshots<cr>", { desc = "Show Failing Snapshots" })

vim.keymap.set("n", "<leader>xd", "<cmd>XcodebuildSelectDevice<cr>", { desc = "Select Device" })
vim.keymap.set("n", "<leader>xp", "<cmd>XcodebuildSelectTestPlan<cr>", { desc = "Select Test Plan" })
vim.keymap.set("n", "<leader>xq", "<cmd>Telescope quickfix<cr>", { desc = "Show QuickFix List" })

vim.keymap.set("n", "<leader>xx", "<cmd>XcodebuildQuickfixLine<cr>", { desc = "Quickfix Line" })
vim.keymap.set("n", "<leader>xa", "<cmd>XcodebuildCodeActions<cr>", { desc = "Show Code Actions" })

[!TIP] Press <leader>X to access the picker with all commands.

Press <leader>xf to access the picker with all Project Manager commands.

Press <C-r> when the picker with devices is presented to refresh the list.

📋 Logs Panel

• Press o on a failed test in the summary section to jump to the failing location
• Press q to close the panel

🧪 Test Explorer

• Press o to jump to the test implementation
• Press t to run selected tests
• Press T to re-run recently selected tests
• Press R to reload test list
• Press [ to jump to the previous failed test
• Press ] to jump to the next failed test
• Press <cr> to expand or collapse the current node
• Press <tab> to expand or collapse all classes
• Press q to close the Test Explorer

⚙️ Configuration

🔥 Customize Xcodebuild.nvim

🎨 Customize Highlights

🤖 Customize Behaviors

📦 Swift Packages Development

This plugin supports only applications. However, if you develop Swift Package for one of supported platforms, you can easily use this plugin by creating a sample iOS/macOS project in your root directory and by adding your package as a dependency.

🔬 Debugger Configuration

nvim-dap plugin lets you debug applications like in any other IDE. On top of that nvim-dap-ui extension will present for you all panels with stack, breakpoints, variables, logs, etc.

To configure DAP for development:

• Download codelldb VS Code plugin from: HERE. For macOS use darwin version.
• Just unzip vsix file and set paths in the configuration below.
• Install also nvim-dap-ui for a nice GUI to debug.
• Make sure to enable console window from nvim-dap-ui to see simulator logs.

return {
  "mfussenegger/nvim-dap",
  dependencies = {
    "wojciech-kulik/xcodebuild.nvim"
  },
  config = function()
    local xcodebuild = require("xcodebuild.integrations.dap")
    -- SAMPLE PATH, change it to your local codelldb path
    local codelldbPath = os.getenv("HOME") .. "/tools/codelldb-aarch64-darwin/extension/adapter/codelldb"

    xcodebuild.setup(codelldbPath)

    vim.keymap.set("n", "<leader>dd", xcodebuild.build_and_debug, { desc = "Build & Debug" })
    vim.keymap.set("n", "<leader>dr", xcodebuild.debug_without_build, { desc = "Debug Without Building" })
    vim.keymap.set("n", "<leader>dt", xcodebuild.debug_tests, { desc = "Debug Tests" })
    vim.keymap.set("n", "<leader>dT", xcodebuild.debug_class_tests, { desc = "Debug Class Tests" })
    vim.keymap.set("n", "<leader>b", xcodebuild.toggle_breakpoint, { desc = "Toggle Breakpoint" })
    vim.keymap.set("n", "<leader>B", xcodebuild.toggle_message_breakpoint, { desc = "Toggle Message Breakpoint" })
    vim.keymap.set("n", "<leader>dx", xcodebuild.terminate_session, { desc = "Terminate Debugger" })
  end,
}

📲 Debugging On iOS 17+ Device

Since iOS 17, a new secure connection between Mac and mobile devices is required. Xcodebuild.nvim uses pymobiledevice3 to establish a special trusted tunnel that is later used for debugging. However, this operation requires sudo (more details).

Showing a pop-up to enter a password every time you run a debugger would be quite annoying. That's why the plugin provides a small script (tools/remote_debugger) that wraps the only two operations requiring sudo (starting a secure tunnel and closing it).

This allows you to configure passwordless access just for this single file and make it work with xcodebuild.nvim. You can even make a local copy if you are worried that the content of this file could be changed in the future.

Passwordless access to remote_debugger

You can disable password requirement by updating /etc/sudoers file. Make sure to use the command below, otherwise you may break your sudo command:

sudo visudo -f /etc/sudoers

Append this line, but first update the path and the username:

YOUR_USERNAME ALL = (ALL) NOPASSWD: /Users/YOUR_USERNAME/.local/share/nvim/lazy/xcodebuild.nvim/tools/remote_debugger

Creating a local copy of remote_debugger

If you don't want to configure the passwordless permission to the file that could be changed in the future, you can make a local copy of this script, set your local path in the config commands.remote_debugger, and update /etc/sudoers accordingly.

Please remember that you will have to update this file manually if it changes in the future.

🐛 Application Logs

If you installed nvim-dap and nvim-dap-ui, you can easily track your app logs. The plugin automatically sends logs to the console window provided by nvim-dap-ui.

To see SIMULATOR logs you don't need to run the debugger. You can just show the console and run the app (remember that the app must be launched using xcodebuild.nvim).

:lua require("dapui").toggle()

[!IMPORTANT] Logs printed by NSLog will appear only if the debugger is NOT attached.

You can always clear the console window by calling:

:lua require("xcodebuild.integrations.dap").clear_console()

Logs without using nvim-dap

If you don't want to use nvim-dap you can always print logs directly to your terminal by calling (from your root directory):

tail -f .nvim/xcodebuild/app_logs.log

This approach works especially well if you are using tmux.

🚥 Lualine Integration

You can also integrate this plugin with lualine.nvim.

🧪 Code Coverage

📸 Snapshot Tests Preview

This plugin offers a nice list of failing snapshot tests. For each test it generates a preview image combining reference, failure, and difference images into one. It works with swift-snapshot-testing library.

Run :XcodebuildFailingSnapshots to see the list.

👨‍💻 API

If you want to use functions directly instead of user commands, then please see xcodebuild.actions module.

🧰 Troubleshooting

[!IMPORTANT] The first thing you should do is to check the output of :checkhealth xcodebuild and fix all issues.

Run it from your project root directory.

Configuration

Processing the project configuration is a very complex task that relies on parsing multiple crazy outputs from xcodebuild commands. Those logs are a pure nightmare to work with. This process may not always work.

In case of any issues with, you can try manually providing the configuration file .nvim/xcodebuild/settings.json in your root directory.

Tests

If you encounter issues with test detection, you may want to read this: Test File Search - File Matching.

LSP

In most cases, it's enough to run the project in Xcode, clean it CMD+Shift+K, build again CMD+B, and run xcode-build-server config again.

Useful Help Tags

• :h xcodebuild
• :h xcodebuild.config
• :h xcodebuild.keys
• :h xcodebuild.tools
• :h xcodebuild.commands
• :h xcodebuild.events
• :h xcodebuild.highlights
• :h xcodebuild.dap