To install this package, run in Emacs:
M-x package-install RET jarchive RET
Jarchive teaches emacs how to open project dependencies that reside inside jar files.
This package is still under active development, but should be relatively stable. Any important or breaking changes will now be noted in the CHANGELOG.
It current works well with eglot on the Emacs master branch. I've also included a patch for legacy versions of eglot that are not yet up to date with Emacs master.
See the CHANGELOG for more information.
After installing this package, in your config call
or it can be called interactively, via
Some Emacs distributions like Doom (and many personal configurations), set the
file-name-handler-alist var to nil on startup, then restore it's value when startup is complete.
If this is the case for you,
jarchive-setup should be called AFTER everything is initialized, using
(with-eval-after-load "init" (jarchive-setup)), where
"init" refers to your
This package modifies
file-name-handler-alist, so it relies on it _not_ being reset after
jarchive-setup is invoked.
Jarchive will open jar dependencies provided to Eglot by lsp servers.
If you are using an older version of Eglot, like the melpa version released on 2022-10-20, then you need to call
jarchive-patch-eglot after Eglot is loaded, like so
This is _not_ required on newer versions of eglot. Installs that are up to date with eglot on ELPA devel or eglot bundled with emacs 29 will work without patching. This patch function is included so those on older releases of eglot can also take advantage of this package. Eventually it will be removed (with some advanced notice).
With it enabled, things like this will open up
page.clj in a read-only buffer.
When using eglot connected to a JVM language server, invoking
xref-find-definitions should correctly open any dependencies that reside in JAR files.
If you want eglot to manage the opened jar'd file in your project's current lsp session, set
(setq eglot-extend-to-xref t)
This will allow xref to work across your project and the opened file.
If you do not want that, the eglot will probably start a new server to manage the newly opened file.
There are legitimate reasons to do this, because including it in the current LSP session will mean it is included when looking up references.
Large files, like the clojure core library, could create a lot of noise in xref lookups.
Another recommendation if you don't want them managed by eglot is to set
(setq eglot-autoshutdown t)
so that the transient lsp server that is started when opening the file is closed along with it.
I personally only test this with clojure-lsp.
I have heard from other users that it also works with some unspecified java language server.
I do know that it does not work with
JDTLS at them moment, which requires all clients to implement custom language server extensions and a complicated non-standard URI scheme to open files in JARs.
Any language server that provides jar: scheme URIs should be picked up by this package. If it doesn't, please let me know and I'd be happy to take a look.
Questions and patches can be submitted to the mailing list.
Bugs can be submitted here: bug tracker. Any bugs found should include steps to reproduce. If possible, and example repository containing a project and instructions (or a nix shell) for installing the language servers would be appreciated.
(with-eval-after-load 'eglot (jarchive-patch-eglot))now in their config instead.
jarchive-patch-eglotattempts to print warnings when it is called at the wrong time.
eglot-extend-to-xrefinstead, or use
M-x write-fileto save where you like.
eglot-extend-to-xrefis working properly.