# External userspace

Currently requires the `qmk-userspace` branch on `qmk_firmware`.

### Userspace commands:

* `qmk userspace-doctor`
* Validates the userspace setup
* `qmk userspace-add -kb <kb> -km <km>`
* Adds a new build target to the list
* If it doesn't have a set of files already, it effectively calls `qmk new-keymap` but targets userspace in the process
* Allows for `-kb all` to allow for effectively building `make all:<km>`
* `qmk userspace-remove -kb <kb> -km <km>`
* Removes a build target from the list
* `qmk userspace-compile`
* Builds all configured targets in userspace
* `qmk userspace-list`
* Lists all build targets -- expands `all:<km>` to equivalent builds

## Done:

Already implemented:

* **@tzarc** has PR [here](https://github.com/qmk/qmk_firmware/pull/22222)
* Support for `$(QMK_USERSPACE)` `make` variable
* `make planck/rev6:me QMK_USERSPACE=../qmk_userspace`
* pulled from env as well, works with qmk_cli in the same way
* people can potentially use `.env`/`.envrc` etc. if they're familiar, won't be promoted by docs
* if currently `cd`ed into a child directory of something that looks like userspace, it'll assume it's userspace, so don't need to mess with environment under normal circumstances
* Support for `qmk config user.overlay_dir=/path/to/my/overlay`
* Allows for out-of-tree compat, people building from `~`
* Support for auto-detection if in a userspace-like directory
* Users can do forks or whatever this way
* `qmk.json` marks a userspace repo, `qmk userspace-doctor` to investigate
* Subset of folder structure as per `qmk_firmware`:
* `layouts/` -- note: removes `default`/`community` level
* `keyboards/`
* `users/`
* Identical pathing as normal `qmk_firmware`:
* `keyboards/planck/rev6/keymaps/me/keymap.c`
* `keymap.c` and `keymap.json` support
* `keymap.json` can live anywhere in repo, but with usual caveats of requiring matching `users/...` if you want to include code external to json
* If userspace is set, `qmk new-keymap` will place the new keymap in the userspace instead
* `qmk.json` at root of userspace controls list of builds
* CLI commands to manipulate the `qmk.json` file, listed below
* Versioned schema validation for userspace `qmk.json` in place already
* Updating using CLI commands saves in latest version

## Future:

* `qmk userspace-setup`
* Mirrors `qmk setup` but does userspace instead
* Describes the creation of a fork of github template repo
* Asks if `user.overlay_dir` should be updated to the new location
* `qmk update-firmware-repo` or equivalent, which pulls the latest