.CLJ File Format – File structure and conventions

Extensions

Namespaces and paths

A lib name is a symbol with usually two or more parts separated by dots. Its file is found on the classpath at a path made from the name: dots become slashes and hyphens become underscores, and the path ends in .class, .clj or .cljc. So com.my-company.utils lives in com/my_company/utils.clj. The lib begins with an ns form that creates the namespace of the same name and declares what it depends on.

(ns com.my-company.clojure.examples.my-utils
  (:import java.util.Date)
  (:use [clojure.string :only (join)])
  (:require [clojure.java.io :as jio]))

The ns form is described on Namespaces and vars.

Load order

When require, use or load looks for a lib, it may find a compiled .class, a .clj and a .cljc. The rules are two:

• a .class file is preferred over source, unless the source file is newer than the class file;
• a .clj file is preferred over a .cljc file. A library author can ship a portable .cljc and add a platform-specific .clj that overrides it.

Files with a fixed name

Running a file

• A namespace with a -main function can be started by name: clojure -M -m my.app. The runtime calls -main with the command-line arguments as strings.
• A script is loaded and run form by form: clojure -M script.clj (clj -M /path/to/myscript.clj arg1 arg2 passes arguments). A first line that starts #! is read as a comment, so a script can begin with a shebang line (Babashka scripts start #!/usr/bin/env bb).
• (load "/my/app/core") loads a resource by its classpath-relative path without the extension (a path that does not begin with a slash is taken relative to the root directory of the current namespace); (load-file "path.clj") loads a file by file path.
• The :gen-class clause of ns makes the namespace compile to a Java class with a main that calls -main, when the namespace is compiled ahead of time; it is ignored when the code is not being compiled.

Ahead-of-time compilation

Clojure compiles everything it loads to JVM bytecode in memory. (compile 'my.domain.lib) writes the result to the directory in *compile-path*, which must be on the classpath. For a namespace it produces a loader class named like the lib with __init added (my/domain/lib__init.class) and one class per function (my/domain/lib$fnname__1234.class), and a stub class for each gen-class. A loader class runs the same static initialiser as loading the source. Reasons to compile ahead of time are to ship without source, to start faster, to name classes for Java, and to avoid runtime bytecode generation and custom class loaders.

Layout of a source file

1. an optional header comment (;;; lines), then the ns form with its documentation string, requires and imports;
2. definitions (def, defn, defmacro, defprotocol, defrecord and so on), top to bottom, because a name must be defined (or declared) before it is used;
3. optionally a -main function at the end;
4. tests of the lib are normally in a parallel namespace named with -test added (my.app.core-test in test/my/app/core_test.clj), written with clojure.test.

Convention, not syntax: ; after code on a line, ;; on a line of its own at the indentation of the code, ;;; and ;;;; for headings in a file. A (comment …) form holds code that is not run and is used for notes and REPL experiments.

Encoding and line endings

Source is text, normally UTF-8. A line comment (; and #!) ends at a line feed or a carriage return, so both Unix and Windows line endings work. A comma is white space, and so are the usual white-space characters of Java (Character.isWhitespace), including the form feed. The viewer reads files as UTF-8 and falls back to Windows-1252 when the bytes are not valid UTF-8.

Not described

Known, not yet covered

• Reference: the Clojure runtime's own start-up sequence (init.clj, clojure.main options) is only touched on; the repl_and_main page of the reference was read for user.clj and -main only.

Unknown

• Reference: the exact set of white-space characters comes from the source of LispReader.java (Character.isWhitespace or a comma); the Java class itself was not run.

See also

• Namespaces and vars – the ns form in full
• Tooling – deps.edn, Leiningen and the build tools
• Common Lisp: file structure – the same question for Common Lisp