The #lang line

Every Racket source file begins with a #lang line. (#lang is pronounced hash-lang.)

The #lang line spec­i­fies what language should be used to inter­pret the source code in the file.

There can be only one #lang line per source file. It’s always the first line of code (though it can be preceded by white­space or comments).

Most often, the simple #lang name nota­tion is used to invoke a language, for instance:

Dialects of languages are typi­cally notated with slashes (e.g., br vs. br/quicklang). (Not all languages have dialects—consult the docu­men­ta­tion to see which are supported.)

This short­hand #lang name nota­tion only works with languages that have been installed as part of a Racket package. Alter­na­tively, you can use the #lang reader path syntax to specify a local path to a language reader, which can be useful for quick proto­types:

Or with #lang s-exp path, you can use Racket’s default S-expres­sion reader with an arbi­trary expander:

More broadly, the #lang line supports meta­lan­guages that can be chained with another language to add new features. For instance, the three language spec­i­fi­ca­tions below all rely on racket/base for the heavy lifting, but the second and third get extra features from the at-exp and debug meta­lan­guages, respec­tively:

Mechanics

Under the hood, the #lang line works by discov­ering the reader for the language, which is a Racket func­tion. Racket passes all the source code after the #lang line to the reader func­tion, which returns code describing a module. Racket then replaces the source code with this new module code, and eval­u­a­tion continues from there.

Logical minds might infer that because a #lang line invokes a reader, and the reader returns syntax for a module expres­sion, then every source file that starts with a #lang line will end up with a single module expres­sion at the top level. Yes—this is exactly right.

In fact, every Racket source file consists of a single module expres­sion at the top level. This is why in Racket lingo, a source file is also known as a module.

Thus, even though the #lang line is highly idiomatic, it’s not tech­ni­cally required. In a Racket source file, you can always use a module expres­sion instead of a #lang line. In prac­tice, there’s no reason to do this, but we can use this to demys­tify what’s happening.

These two programs are the same, and will both print 42:

This program is different, however:

It doesn’t print 42 because the #lang line intro­duces its own module wrap­ping, so you end up with nested modules like so:

Though Racket auto­mat­i­cally eval­u­ates the top-level module, it doesn’t auto­mat­i­cally eval­uate nested modules, so submod-name never runs.

Caution: in the above exam­ples, you could easily convert to module form because racket/base source code uses Racket’s stan­dard S-expres­sion reader. But in general, a module expres­sion standing alone can’t invoke a special reader. So even though this would be valid Scribble code:

You can’t do this:

More broadly, this means you can’t mix different readers within a single source file. There can be only one #lang line, and it deter­mines the reader for the whole file.

Anything on the #lang line that follows the name of the main language is treated as part of the source code. So this prints 42:

You can put Racket-style comments before the #lang line, so this also prints 42:

Racket has no offi­cially sanc­tioned way of passing config­u­ra­tion argu­ments to a language on the #lang line (maybe someday—it would be useful). Certain languages like scribble/doclang2 support things that look like keyword argu­ments. But in fact, these argu­ments are part of the source code, and are being handled specially by the language’s read-syntax func­tion.

Further