GNU ELPA - jarchive

jarchive

Description
Open project dependencies in jar archives
Latest
jarchive-0.11.0.tar (.sig), 2023-Oct-11, 30.0 KiB
Maintainer
Danny Freeman <danny@dfreeman.email>
Website
https://git.sr.ht/~dannyfreeman/jarchive
Browse ELPA's repository
CGit or Gitweb
Badge

To install this package from Emacs, use package-install or list-packages.

Full description

Jarchive teaches emacs how to open project dependencies that reside inside jar files.

Package status

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.

Installing

This package is available on ELPA. There is also an example of a guix recipe.

After installing this package, in your config call jarchive-mode:

emacs-lisp (jarchive-mode)

or it can be called interactively, via M-x jarchive-mode.

Doom Emacs users: Note about when to call jarchive-mode

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-mode should be called AFTER everything is initialized, using (with-eval-after-load "init" (jarchive-mode)), where "init" refers to your "init.el" file. This package modifies file-name-handler-alist, so it relies on it _not_ being reset after jarchive-mode is invoked.

Working with Eglot

Jarchive will open jar dependencies provided to Eglot by lsp servers. This should work out of the box with Emacs 29 and recent Eglot versions.

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

emacs-lisp (jarchive-patch-eglot)

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. It is currently marked obsolete and will be removed in the next version of Jarchive.

Usage

With it enabled, things like this will open up page.clj in a read-only buffer.

emacs-lisp (find-file "jar:file:///.m2/repository/hiccup/hiccup/1.0.5/hiccup-1.0.5.jar!/hiccup/page.clj")

When using eglot connected to a JVM language server, invoking xref-find-definitions should correctly open any dependencies that reside in JAR files.

Other usage considerations

If you want eglot to manage the opened jar'd file in your project's current lsp session, set emacs-lisp (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 emacs-lisp (setq eglot-autoshutdown t) so that the transient lsp server that is started when opening the file is closed along with it.

Language server compatibility

I personally only test Jarchive with clojure-lsp.

Users report that Jarchive works well with the Java LSP server 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 Bugs

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.

Old versions

jarchive-0.10.0.tar.lz2023-Jan-185.70 KiB
jarchive-0.9.0.tar.lz2022-Dec-085.61 KiB
jarchive-0.8.0.tar.lz2022-Nov-145.50 KiB
jarchive-0.6.0.tar.lz2022-Nov-135.38 KiB
jarchive-0.3.0.tar.lz2022-Nov-135.41 KiB

News

Change Log

2023-10-10 0.11.0 Release Notes

  • Fixes a bug when file-relative-name is called on a buffer opened by jarchive.
    • See bug#2 for more details.
    • Thank you lassemaatta for the bug report
  • Allow jarchive to be disabled via a new global minor mode
    • jarchive-setup is now obsolete. Please use jarchive-mode instead.
  • jarchive-patch-eglot is now marked as obsolete.
    • If you are still using this, please update to a more recent version of Eglot

2023-01-18 0.10.0 Release Notes

  • Thank you Robert Brown for the following contributions:
    • Handle opening archives with the .zip extension
    • Handle opening files (within archives) that do not have a . in the name
    • Some cleanup in the README

2022-12-07 0.9.0 Release Notes

  • Add missing file-name-handler operations
    • Thank you Michael Albinus for pointing this out on the bug-gnu-emacs mailing list!

2022-11-14 0.8.0 Release Notes

  • Readme Changes

2022-11-13 0.7.0 Release Notes

  • Add info about jarchive on ELPA

2022-11-13 0.6.0 Release Notes

  • Add link to bug tracker

2022-11-13 0.5.0 Release Notes

  • Fix Typo

2022-11-13 0.4.0 Release Notes

  • Remove some unnecessary messages
  • Misc non breaking fixes
  • Quiet down eglot patch messages in case it's called from a hook

2022-11-12 0.3.0 Release Notes

  • Assigned copyright to Free Software Foundation (elpa requirement)
  • Bumped version in jarchive.el to 0.3.0 (forgot to bump to 0.2.0 in last version)

2022-11-12 0.2.0 Release Notes

  • Documentation updates in preparation for submitting to elpa or melpa
  • BREAKING: Patching legacy Eglot no longer happens automatically when calling jarchive-setup.
    • Users can call (with-eval-after-load 'eglot (jarchive-patch-eglot)) now in their config instead.
  • jarchive-patch-eglot attempts to print warnings when it is called at the wrong time.

2022-11-11 0.1.0 Release Notes

  • Now operates on full jar URIs and zipfile URIs
    • For example jar:file:///path/to/library.jar!/path/in/jar/source.ext
    • also zipfile:///path/to/library.jar::/path/in/jar/source.ext
  • Removed command jarchive-move-to-visiting-project
    • Prefer setting eglot-extend-to-xref instead, or use M-x write-file to save where you like.
  • Removed jarchive--managed-mode
    • No longer necessary now that eglot-extend-to-xref is working properly.
  • Works with the latest eglot on emacs master
  • Patches the legacy eglot (version 1.9, released 2022-10-11) on melpa that does not contain the changes from above commit to emacs mainline
    • Currently what is available to stable emacs users (version 28.x)
    • https://elpa.gnu.org/packages/eglot.html