clojure / clojure/clojure-site
Add guidance on when to use AOT compilation
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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