{"id":13477950,"url":"https://github.com/kkharji/xbase","last_synced_at":"2025-04-04T20:15:53.155Z","repository":{"id":36975583,"uuid":"482645470","full_name":"kkharji/xbase","owner":"kkharji","description":"Develop Apple software products within your favorite editor. ","archived":false,"fork":false,"pushed_at":"2024-01-28T11:49:10.000Z","size":32574,"stargazers_count":545,"open_issues_count":29,"forks_count":17,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-28T19:11:48.154Z","etag":null,"topics":["apple","codegen","ide","ios","lua","macos","neovim","nvim","rust","vim","vscode","xcode"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kkharji.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2022-04-17T22:17:57.000Z","updated_at":"2025-03-25T04:52:53.000Z","dependencies_parsed_at":"2024-08-13T22:15:54.047Z","dependency_job_id":"ad6a11da-2c4c-41cf-8014-a7d069188d0f","html_url":"https://github.com/kkharji/xbase","commit_stats":null,"previous_names":["xbase-lab/xbase"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkharji%2Fxbase","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkharji%2Fxbase/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkharji%2Fxbase/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkharji%2Fxbase/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kkharji","download_url":"https://codeload.github.com/kkharji/xbase/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247242681,"owners_count":20907134,"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","codegen","ide","ios","lua","macos","neovim","nvim","rust","vim","vscode","xcode"],"created_at":"2024-07-31T16:01:50.216Z","updated_at":"2025-04-04T20:15:53.136Z","avatar_url":"https://github.com/kkharji.png","language":"Rust","readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"./.github/media/logo.png\" alt=\"Logo\" /\u003e\n\u003c/P\u003e\n\nAn Xcode replacement-ish *development environment* that aims to be your reliable Xcode alternative to develop exciting new [apple] software products 🚀.\n\n## Table of Content\n\n- [👁  Overview]\n- [🌝 Motivation]\n- [🌟 Features]\n- [💆 Generators]\n- [🛠 Requirements]\n- [🦾 Installation]\n- [🎮 Usage]\n- [⚙️ Defaults]\n- [🩺 Debugging]\n- [🎥 Preview]\n\n## 👁 Overview\n\n[XBase] enables you to build, watch, and run xcode products as well as swift packages from within your favorite editor. It supports running products on iOS, watchOS and tvOS simulators, along with real-time logging, and some lsp features such as auto-completion and code navigation. ([🌟 Features](#-features)).\n\nFurthermore, [XBase] has built-in support for a variety of Xcode project generators, which allow you to avoid launching Xcode or manually editing '*.xcodeproj' anytime you add or remove files. We strongly advise you to use one ... at least till [XBase] supports adding/removing files and folders, along with other requirements. ([💆 Generators](#-generators))\n\nPlease be aware that [XBase] is still **WIP**, so don't hesitate to report bugs, ask questions or suggest new exciting features.\n\n\n## 🌝 Motivation\n\nI chose to dive into iOS/macOS app development after purchasing an M1 MacBook. However, coming from vim/shell environment and being extremely keyboard oriented, I couldn't handle the transition to a closed sourced, opinionated, mouse-driven development environment. I've considered alternatives like [XVim2] and the built-in vim emulator, however still, I'd catch myself frequently hunting for my mouse.\n\nAs a long-time vim user who has previously developed a several lua/nvim plugins, I decided to invest some effort in simplifying my development workflow for producing 'xOS' products.\n\n## 🌟 Features\n\n* **Auto-Completion and Code navigation**\\\n    Auto-generate compilation database on directory changes + a custom build server that assists [sourcekit-lsp] in providing code navigation and auto-completion for project symbols.\n* **Multi-nvim instance support**\\\n    Multiple nvim instance support without process duplications and shared state. For instance, you can stop a watch service that was being run from a different instance.\n* **Auto-start/stop main background daemon**\\\n    Daemon will start and stop automatically based on the number of connected client instances.\n* **Multi Target/Project Support**\\\n    Work on multiple projects at one nvim instance at the same time.\n* **Simulator Support**\\\n    Run your products on simulators relative to your target's platform. (+ watch build and ran on change)\n* **Runtime/Build Logging**\\\n    Real-time logging of build logs and 'print()' commands\n* **Statusline Support**\\\n    Global variable to update statusline with build/run commands, see [Statusline](#statusline)\n* **Zero Footprint**\\\n    Light resource usage. I've been using [XBase] for a while; it typically uses 0.1 percent RAM and 0 percent CPU.\n* **Multi XcodeProj Generator Support**\\\n    Auto-generate xcodeproj, when it doesn't exists, generator config files a updated or new files/directories added or removed.\n* **Swift Package Support**\\\n    Auto-generate when `.build` folder doesn't exists, Package.swift file is updated or new files or directories are added or removed.\n\n## 💆 Generators\n\n[XBase] primarily supports two project generators: [XcodeGen] and [Tuist].\n\n[XcodeGen] is **recommended** if you are just starting started with `xcodeproj generators`\nsince it is considerably simpler with a yml-based configuration language. Having said that,\n[Tuist] is more powerful and packed with features, of which `xcodeproj generation` is but one.\n\n[XBase]'s support for generators is available in the following forms:\n\n- Identification.\n- Auto-generate xcodeproj if you haven't haven't generate it by hand.\n- Auto-generate xcodeproj when you edit the generator config files.\n- Auto-compile project when xcodeproj get regenerated.\n- Code Completion and navigation (#tuist)\n\n### Limitations\n\n#### [XcodeGen]\n\n- No support for custom named yml config files, only `project.yml`.\n\n#### Other Generators\n\nWith current [XBase] architecture, it should be pretty easy to add support for yet another\nawesome xcodeproj generator. feel free to get started with [CONTRIBUTING.md] or open a github\nissue\n\n## 🛠 Requirements\n\n### Shared\n\n- \u003ckbd\u003e[rust] ^1.60\u003c/kbd\u003e \u003csub\u003ecompile project locally\u003c/sub\u003e\n\n### Neovim\n\n- \u003ckbd\u003e[neovim] ^0.7\u003c/kbd\u003e \u003csub\u003eNeovim Editor.\u003c/sub\u003e\n- \u003ckbd\u003e[lspconfig] *\u003c/kbd\u003e \u003csub\u003eLSP integration.\u003c/sub\u003e\n- \u003ckbd\u003e[telescope.nvim]  ^0.1\u003c/kbd\u003e \u003csub\u003ebetter picker UI experience \u003ckbd\u003eoptional\u003c/kbd\u003e\u003c/sub\u003e\n- \u003ckbd\u003e[dressing.nvim]  *\u003c/kbd\u003e \u003csub\u003esupport for other neovim ecosystem pickers  \u003ckbd\u003eoptional\u003c/kbd\u003e\u003c/sub\u003e\n\n### Vscode\n\n\u003ckbd\u003eTODO\u003c/kbd\u003e\n\n\n\n## 🦾 Installation\n\nTo install [XBase] on your system you need run `make install`. This will run `cargo build\n--release` and resulting binrary to `~/.local/share/xbase/`.\n\n### Neovim\n\n#### With [packer]\n```lua\nuse {\n  'xbase-lab/xbase',\n    run = 'make install', -- or \"make install \u0026\u0026 make free_space\" (not recommended, longer build time)\n    requires = {\n      \"neovim/nvim-lspconfig\",\n      -- \"nvim-telescope/telescope.nvim\", -- optional\n      -- \"nvim-lua/plenary.nvim\", -- optional/requirement of telescope.nvim\n      -- \"stevearc/dressing.nvim\", -- optional (in case you don't use telescope but something else)\n    },\n    config = function()\n      require'xbase'.setup({})  -- see default configuration bellow\n    end\n}\n```\n\n#### With [vim-plug]\n```vim\n\" Plug 'nvim-telescope/telescope.nvim' \" optional\n\" Plug 'nvim-lua/plenary.nvim' \" optional/requirement of telescope\n\" Plug 'stevearc/dressing.nvim' \" optional/in case you don't use telescope but use something else\nPlug 'neovim/nvim-lspconfig'\nPlug 'xbase-lab/xbase', { 'do': 'make install' }\nlua require'xbase'.setup()\n```\n\n#### With [dein]\n```vim\n\" call dein#add('nvim-telescope/telescope.nvim') \" optional\n\" call dein#add('nvim-lua/plenary.nvim') \" optional/requirement of telescope\n\" call dein#add('stevearc/dressing.nvim') \" optional/in case you don't use telescope but use something else\ncall dein#add('neovim/nvim-lspconfig')\ncall dein#add('xbase-lab/xbase', { 'build': 'make install' })\nlua require'xbase'.setup()\n```\n\n\u003e **NOTE:** You need to setup sourcekit-lsp (see [sourcekit-setup]) and consider adding more\n\u003e file to root patterns\n\n### Vscode\n\n\u003ckbd\u003eTODO\u003c/kbd\u003e\n\n## 🎮 Usage\n\n### Neovim\n\nTLDR:\n- [Install XBase](#-installation)\n- run `require'xbase'.setup({ --[[ see default configuration ]]  })`\n- Open xcodeproj codebase.\n- Wait for first time project setup finish.\n- Start coding\n- Use available actions which can be configure with shortcuts bellow\n\nWhen you start a neovim instance with a root that contains `project.yml,` `Project.swift,` or\n`*.xcodeproj,` the daemon server will auto-start if no instance is running, and register the\nproject once for recompile-watch. To communicate with your daemon, checkout the configurable\nshortcuts.\n\n### Statusline\n\n[XBase] provide [feline] provider, other statusline plugins support are welcomed. However,\nusing `vim.g.xbase_watch_build_status` you can easily setup statusline indicators.\n\n```lua\nrequire(\"xbase.statusline\").feline() -- append to feline setup function\n```\n\n### Vscode\n\n\u003ckbd\u003eTODO\u003c/kbd\u003e\n\n## ⚙️ Defaults\n\n### Neovim\n```lua\n-- NOTE: Defaults\n{\n  --- Log level. Set it to ERROR to ignore everything\n  log_level = vim.log.levels.DEBUG,\n  --- Options to be passed to lspconfig.nvim's sourcekit setup function.\n  --- Setting this to {} is sufficient, However, it is strongly recommended to use on_attach key to setup custom mappings\n  --- {\n  --- cmd = { \"sourcekit-lsp\", \"--log-level\", \"error\" },\n  --- filetypes = { \"swift\" },\n  --- root_dir = pattern(\"Package.swift\", \".git\", \"project.yml\", \"Project.swift\"),\n  --- }\n  sourcekit = nil, -- Disabled by default (xbase will not call it for you)\n  --- Statusline provider configurations\n  statusline = {\n    watching = { icon = \"\", color = \"#1abc9c\" },\n    device_running = { icon = \"\", color = \"#4a6edb\" },\n    success = { icon = \"\", color = \"#1abc9c\" },\n    failure = { icon = \"\", color = \"#db4b4b\" },\n  },\n  --- Simulators to only include.\n  --- run `xcrun simctl list` to get a full list of available simulator\n  --- If the list is empty then all simulator available  will be included\n  simctl = {\n    iOS = {\n      -- \"iPhone 13 Pro\", --- only use this devices\n    },\n    watchOS = {}, -- all available devices\n    tvOS = {}, -- all available devices\n  },\n  --- Log buffer configurations\n  log_buffer = {\n    --- Whether toggling the buffer should auto focus to it?\n    focus = true,\n    --- Split Log buffer height\n    height = 20,\n    --- Vsplit Log buffer width\n    width = 75,\n    --- Default log buffer direction: { \"horizontal\", \"vertical\" }\n    default_direction = \"horizontal\",\n  },\n  --- Mappings\n  mappings = {\n    --- Whether xbase mapping should be disabled.\n    enable = true,\n    --- Open build picker. showing targets and configuration.\n    build_picker = \"\u003cleader\u003eb\", --- set to 0 to disable\n    --- Open run picker. showing targets, devices and configuration\n    run_picker = \"\u003cleader\u003er\", --- set to 0 to disable\n    --- Open watch picker. showing run or build, targets, devices and configuration\n    watch_picker = \"\u003cleader\u003es\", --- set to 0 to disable\n    --- A list of all the previous pickers\n    all_picker = \"\u003cleader\u003eef\", --- set to 0 to disable\n    --- horizontal toggle log buffer\n    toggle_split_log_buffer = \"\u003cleader\u003els\",\n    --- vertical toggle log buffer\n    toggle_vsplit_log_buffer = \"\u003cleader\u003elv\",\n  },\n}\n```\n\n### Vscode\n\n\u003ckbd\u003eTODO\u003c/kbd\u003e\n\n## 🩺 Debugging\n\nSometimes xcodebuild acts up and things might break, the first step to find the root cause is\nto check logs. The following is how you can have a stream of logs in your terminal.\n\n```bash\n# Daemon logs\ntail -f /tmp/xbase.log\n# Build Server logs\ntail -f /tmp/xbase-build-server.log\n```\n\nIn case, you need to manually stop servers:\n\n```bash\nkillall xbase xbase-sourcekit-helper\n```\n\n[xcodegen]: https://github.com/yonaskolb/XcodeGen\n[sourcekit-lsp]: https://github.com/apple/sourcekit-lsp\n[XBase]: https://github.com/xbase-lab/xbase\n[xcodebuild]: https://github.com/xbase-lab/xcodebuild\n[feline]: https://github.com/feline-nvim/feline.nvim\n[XVim2]: https://github.com/XVimProject/XVim2\n[rust]: https://www.rust-lang.org\n[tuist]: https://github.com/tuist/tuist\n[dein]: https://github.com/Shougo/dein.vim\n[packer]: https://github.com/wbthomason/packer.nvim\n[vim-plug]: https://github.com/junegunn/vim-plug\n[rust getting started]: https://www.rust-lang.org/tools/install\n[telescope.nvim]: https://github.com/nvim-telescope/telescope.nvim\n[plenary.nvim]: https://github.com/nvim-lua/plenary.nvim\n[neovim]: https://github.com/neovim/neovim\n[tuist]: https://github.com/tuist/tuist\n[dev.md]: ./dev.md\n[lspconfig]: https://github.com/neovim/nvim-lspconfig\n[sourcekit-setup]: https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#sourcekit\n[apple]: https://github.com/apple\n[dressing.nvim]: https://github.com/stevearc/dressing.nvim\n\n[👁  Overview]: #-motivation\n[🌝 Motivation]: #-motivation\n[🌟 Features]: #-features\n[💆 Generators]: #-generators\n[🛠 Requirements]: #-requirements\n[🎮 Usage]: #-usage\n[🦾 Installation]: #-installation\n[⚙️ Defaults]: #-defaults\n[🩺 Debugging]: #-debugging\n[🎥 Preview]: #-preview\n","funding_links":[],"categories":["Rust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkkharji%2Fxbase","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkkharji%2Fxbase","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkkharji%2Fxbase/lists"}