Behavior and documentation of .cljc file loading

[Andy Fingerhut]

If one has in their Java classpath a directories A then later B, the order that source files are checked for in Clojure 1.7.0 when one does (require 'foo.bar) is this (assume no .class files exist for this example):

A checked for foo/bar.clj
B checked for foo/bar.clj

A checked for foo/bar.cljc
B checked for foo/bar.cljc

This means that if you have and use a foo/bar.cljc file somewhere in your classpath, and later you add a new directory X to the end of your classpath that contains foo/bar.clj, then the new one will be used in preference to the foo/bar.cljc file.

Is this intended, and if so, is it documented anywhere?  I could not find a mention of it in the official docs.


Places I saw .clj mentioned, but should also probably mention .cljc files, too.


On this page: http://clojure.org/libs under the heading "Lib Conventions" it says 'The path ends with ".clj"'.  Should now be extended with 'or ".cljc"'

Similarly for the doc string for clojure.core/require.

clojure.core/use does not appear to need any updates, since it says "Like 'require".  I don't know why clojure.core/use's doc string has the quotes before 'require and 'use.

Andy

[Thomas Heller]

I looked this up recently since I wanted to implement the behaviour for cljs. All I could find was the definition on the design page, I guess this counts as official documentation.

When finding a library in any Clojure dialect, the platform-specific resource will be found and loaded first (.clj or .cljs) before the portable file (.cljc) is found or loaded. This allows the opportunity to override a platform-agnostic file with a platform-specific implementation of a namespace.

http://dev.clojure.org/display/design/Reader+Conditionals

Cheers,

/thomas

[Alex Miller]

This is the expected (and intentional) behavior.

The only place in the reference docs where cljc are mentioned currently is on the reader page. Libs is probably the most appropriate place to mention this, but happy to take other suggestions. I'm going to just file an issue for this in the new site repo rather than fix it on the live site.

Alex