init.lua configuration portability across environments with missing system binaries

Answer

Use vim.fn.executable('binary_name') (or vim.loop.spawn with a check) to test whether a required system binary exists before any Lua code that invokes it runs. Conditionally enable the dependent plugin, keymaps, or feature based on the result, and provide a pure‑Lua fallback or a user notification when the binary is missing.

Steps to implement

1. Define a small helper (optional) that returns a boolean:

   local function has_bin(name)
     return vim.fn.executable(name) == 1
   

2. Guard plugin loading or setup:

   if has_bin('rg') then
     require('telescope').setup{
       defaults = { vimgrep_arguments = { 'rg', '--color=never', '--no-heading', ... } }
     }
     -- set keymaps that use ripgrep
   else
     vim.notify('ripgrep not found – falling back to vim.grep', vim.log.levels.WARN)
     -- optionally disable the telescope live_grep picker or provide a pure‑Lua fallback
   end

3. If you use a plugin manager that supports lazy loading, pass a conditional config:

   -- example with lazy.nvim
   {
     'nvim-telescope/telescope.nvim',
     cond = function() return vim.fn.executable('rg') == 1 end,
     config = function() require('telescope').setup(...) end,
   }

4. Provide a fallback for any keymap or command that would otherwise error:

   if not has_bin('fd') then
     vim.keymap.set('n', 'f', function()
       vim.notify('fd missing – using built‑in findfiles', vim.log.levels.INFO)
       require('telescope.builtin').find_files()
     end, { desc = 'Find files (fd fallback)' })
   else
     vim.keymap.set('n', 'f', 'Telescope fd find_files', { desc = 'Find files with fd' })
   end

Likely explanation vs. confirmed facts

Likely explanation: When a binary such as rg or fd is absent, any Lua code that calls it via vim.system, vim.fn.jobstart, or a plugin’s internal command will raise an error, causing Neovim to stall or display a traceback during startup.

Confirmed facts: vim.fn.executable returns 1 if the executable is found in the user’s $PATH, 0 otherwise; it is a synchronous, lightweight check suitable for init.lua. Plugins that respect a disabled flag or are loaded lazily will not attempt to call the missing binary, preventing runtime errors.