Leiningen Documentation

Leiningen Core provides task execution, project configuration, and helper functions. The following namespaces are the primary entry points for core functionality:

• leiningen.core.main: Contains the -main entry point and task handling functions like apply-task and resolve-task.
• leiningen.core.project: Provides read and defproject to obtain project maps from project.clj files. It also manages profile application and plugin loading.
• leiningen.core.classpath: Responsible for calculating the project's classpath, including Maven and checkout dependencies.
• leiningen.core.eval: Contains eval-in-project, which implements project code isolation.
• leiningen.core.user: Provides functions for handling user-level configuration.

To make your project available as a dependency for others, you can publish it to Clojars.

Steps to publish:

1. Create a Clojars account.
2. Update your project.clj to include your verified group name (e.g., org.clojars.username/project-name).
3. Generate a deploy token from Clojars.
4. Run lein deploy clojars.

Note: For non-snapshot releases, Leiningen may attempt to sign the release using GPG or SSH to prove authorship.

Leiningen executes tasks by following these steps:

1. Reads the project.clj file.
2. Applies active profiles to the resulting project map.
3. Looks up the requested task. Tasks are functions defined in the leiningen.the-task namespace, typically named after the task itself.
4. Uses apply-task to verify the task can be applied to the provided arguments and then executes it.

Tasks usually accept a project map as an argument, though they can run outside a project context. For details on writing custom tasks, refer to the plugin guide.

Project middleware is a function that takes a project map and returns a transformed project map. It is used for programmatic transformations that cannot be achieved via profiles.

Usage in project.clj:

:middleware [leiningen.inject/middleware]

Best Practices:

• Idempotency: Middleware functions may be called repeatedly when profiles change; ensure they have no non-idempotent side-effects.
• Prefer Profiles: Use plugin profiles instead of middleware whenever possible for better transparency and easier debugging.
• Avoid Implicit Loading: Do not rely on the implicit plugin-name.plugin/middleware naming convention; it is difficult to debug and strongly advised against.

For most project-specific command-line needs, it is simpler to use an alias that invokes a -main function within your project code rather than writing a full plugin.

Arguments provided during the CLI invocation are concatenated to the arguments defined in the alias vector. For example, if your alias is ["run" "-m" "myproject.garble" "supergarble"], running lein garble seventeen results in the arguments "supergarble" "seventeen" being passed to the -main function.

:aliases {"garble" ["run" "-m" "myproject.garble" "supergarble"]}

To test a plugin in a separate project, build and install it to your local Maven repository:

1. In the plugin directory, run:

lein install

2. Note the version outputted (e.g., 0.1.0-SNAPSHOT).
3. In your test project's project.clj, add the plugin to the :plugins vector:

:plugins [[sample-plugin "0.1.0-SNAPSHOT"]]

GPG (Gnu Privacy Guard) is required for signing artifacts for publication to Clojars and encrypting repository credentials. Installation methods vary by operating system:

• Linux: Use your distribution's package manager (e.g., apt install gnupg or yum install gnupg).
• macOS:
  • Homebrew: brew install gnupg
  • MacPorts: port install gnupg
  • Binary installer: Use GPGTools.
• Windows: Use the GPG4Win binary installer, or use WSL.

If your project requires alternating between compiling Clojure and Java (e.g., when Java code depends on AOT-compiled Clojure namespaces, or when Java code is generated from other sources), you can use Leiningen profiles to manage the sequence.

1. Create a pre-compilation profile: Define a profile (e.g., :precomp) that includes the necessary :aot namespaces and potentially :prep-tasks for code generation.
2. Run the pre-compilation: Execute lein with-profile <profile-name> compile.
3. Run standard tasks: Once the pre-compilation is complete, run standard tasks like lein test or lein uberjar, which will then perform the remaining javac and compile steps using the default profile.

If you cannot use a package manager, you can install Leiningen manually. Leiningen installs itself automatically on its first run.

Prerequisites:

• Java installed (OpenJDK is recommended).

Steps:

1. Download the lein script from the stable branch of the repository.
2. Place the script in your $PATH (e.g., /usr/local/bin).
3. Make the script executable: sudo chmod +x /usr/local/bin/lein.
4. Run lein to complete the installation.

Note for Windows users: Use the provided lein.bat or lein.ps1 files, or run the script via WSL.

To avoid running lein install repeatedly during development, you can use a .lein-classpath file in your test project:

1. Run lein install in the plugin directory once.
2. Verify the plugin is visible by running lein help <plugin-name> in the test project.
3. Create or edit a .lein-classpath file in the test project directory.
4. Add the absolute path to the plugin's src directory to .lein-classpath.
5. If the plugin has dependencies you are also developing, add their src paths to .lein-classpath using the platform-specific separator (: for Unix, ; for Windows). Use lein classpath to verify the format.
6. Important: Remove the plugin entry from the test project's project.clj to prevent it from overriding the .lein-classpath settings.

To use {{name}} only for a specific project, add the plugin dependency to the :plugins vector within that project's project.clj file.

[{{name}} "0.1.0-SNAPSHOT"]