clojure / clojure/clojure-site

Add guidance on when to use AOT compilation

Open
#633 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
HTML
Stars
259
Forks
275
PR merge metrics
No merged PRs in 30d

Description

There is a good reference on AOT compilation, but I don't see strong guidance on when to use it, or more specifically when to not use it.

My understanding is that it is relatively safe to employ AOT compilation for an app.

But sometimes a library author will naively use AOT compilation when creating their release jar without realizing the problems this can cause for users of their library. These problems include (additions and corrections most welcome):

  • aot compilation will create class files for library dependencies, this effectively brings in these dependencies (or portions of dependencies) at jar creation time, rather than runtime. A user might bring in different versions of those dependencies. Having multiple instances of a dependency on the classpath at runtime leads to confusion.
  • a class file will not include metadata such as original clojure filename and line number.
  • different versions of Clojure can generate different bytecode

I suppose a note on how/when to safely employ AOT compilation for a lib might also be helpful.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the existing AOT compilation reference linked in the issue and identify where guidance on use and non-use belongs. Add documented guidance for application and library authors, including the listed dependency, metadata, and Clojure-version concerns. Done means the documentation clearly explains when AOT is appropriate and how library authors can use it safely.

Written by the indexing model from the issue text.

Assessment

Tech stack
clojure
Domain
compilers, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.