Next: , Up: Getting Started: Installation and First Speech   [Contents][Index]

3.2 Before You Begin

Install git to obtain the checkout. Emacsvox requires Emacs 30.2 or newer. WSL2 users can let the guided installer inspect an existing Emacs, suggest a suitable package, or offer an explicit source build. It does not begin an Emacs source build by default.

On GNU/Linux and macOS, install Emacs 30.2 or newer and make. Omnivox 1.18.0 or newer is the supported speech-server baseline. On macOS, use Homebrew for Omnivox as described in Installing An Omnivox Release Binary; Emacs and Emacsvox are installed separately. Manual release-archive installation requires curl, tar, and sha256sum on GNU/Linux or shasum on macOS. GNU Texinfo is needed for building or editing the documentation, not for an ordinary installation.

Ubuntu 26.04 provides Emacs 30.2 as a distribution package. The same Emacs minimum applies to native Windows. On Emacs 30, install lua-mode separately if you use Lua; it is built into Emacs 31. Corfu on an Emacs 30 text terminal also needs corfu-terminal; Emacs 31 supports its terminal popup directly.

Check the Emacs found by your shell: 

emacs --version

The reported version must be 30.2 or newer. If the command is missing or reports an older version, install a supported Emacs or locate its executable. You can check a specific executable in the same way: 

/path/to/emacs-31/bin/emacs --version

3.2.1 Prepare the settings-menu dependency

Emacsvox requires Transient 0.13.3 or newer. Emacs 31 supplies a supported version; Emacs 30.2’s bundled 0.7.2.2 needs an upgrade before building Emacsvox. Use your selected Emacs and its package manager, with GNU ELPA enabled:

  1. Run M-x set-variable RET package-install-upgrade-built-in RET t RET. Answer the variable-name and value prompts separately. This permits package dependencies to replace older built-in copies in this Emacs session; it does not save a new startup preference. See Examining and setting variables in the GNU Emacs Manual for this command.
  2. Run M-x package-refresh-contents RET, then M-x package-upgrade RET transient RET. Accept the package’s dependencies.
  3. Start a fresh Emacs before building or trying the menus. A running session can retain the older loaded version after installation.

An isolated Emacsvox session activates an installed Transient and its required packages when its bundled version is too old. It does not load your init file, activate unrelated packages, or download dependencies. Install into the package directory used by the same Emacs profile; a custom package directory must be on that session’s load path. Debian installations also discover the system ELPA directory without site startup.

If a menu reports an unsupported version, inspect the version and loaded path in its error. Upgrade that installation and restart Emacs; restarting only speech does not replace loaded Lisp. The Emacs minimum remains 30.2.

3.2.2 Obtain the development checkout

Run the clone from a terminal on GNU/Linux, macOS, or WSL. The following location works for an ordinary per-user installation and selects the branch described by this manual: 

mkdir -p ~/src
cd ~/src
git clone --branch ui-experiments https://github.com/bartbunting/emacsvox
cd emacsvox

For an existing checkout, inspect git status --short and git branch --show-current before changing branches or updating. Do not replace or discard local work to make the checkout match an example.

The checkout is the installation directory. It builds in place and does not create a second tree to copy elsewhere. Under WSL, keep it on the Linux filesystem, not below a Windows-mounted path such as /mnt/c; Windows filesystem semantics can interfere with Unix executable permissions and build tools. Clone Omnivox beside Emacsvox only for an Omnivox source build or the advanced reproducible WSL2 build.

3.2.3 Use the guided WSL2 installer

For a local WSL2 desktop, first inspect the machine without changing it: 

cd ~/src/emacsvox
./bin/emacsvox-wsl-install --check

If Emacs is missing, the report checks the available apt version and suggests sudo apt install emacs only when that candidate satisfies 30.2. Older or unavailable candidates are identified without being recommended. Refresh apt metadata and check again, or choose the pinned source build with ./bin/emacsvox-wsl-install --build-emacs. Add --check to inspect that build’s prerequisites first.

With Emacs selected, the report names it, the matching Omnivox Windows archive, and the per-user installation paths. If source-build packages are missing, it prints one apt command for you to review and run. The installer never invokes sudo itself. After resolving reported prerequisites, run: 

./bin/emacsvox-wsl-install

If you chose --build-emacs, include that option in the installation command. It prepares the pinned stable Emacs for your user. The installer then downloads and verifies the matching Omnivox 1.18.0 Windows archive, records its path without editing a shell startup file, compiles Emacsvox, runs a diagnostic, and plays the final speech-server check. Later runs reuse the Emacs build and verified downloads.

Routine compiler output is kept below $XDG_CACHE_HOME/emacsvox/logs, normally ~/.cache/emacsvox/logs. If a build fails, the installer shows its final log lines and the complete log path. Continue only after hearing both the final tone and speech. You can then go to the final step in Quick Installation and start Emacsvox. Optional engines can wait until first speech is working.

Next: Installing On A Remote Linux Host, Up: Getting Started: Installation and First Speech   [Contents][Index]