RKT file format: File structure

Racket reads a file as a sequence of Unicode characters and turns it into one module. What the file may contain depends on its first line, which names the language of the module. This page covers the files that belong to Racket, what each extension means, and how a module begins.

Extensions and names

Name	Holds	Notes
`.rkt`	A module, in the language its `#lang` line names	The ordinary Racket source file. Racket treats the extension as the default for module files; `(require "x.rkt")` and `racket x.rkt` read it.
`info.rkt`	A package or collection description	A module written in `#lang info` that defines names such as `collection` and `deps`. The viewer reads it by name; see Packages and raco.
`.rktl`	Code that is loaded with `load` rather than required	A convention, not a rule of the language: the Racket tools use it for files read form by form into a namespace, with no `module` wrapper.
`.rktd`	Data: one or more S-expressions written to be read with `read`	A convention. Racket's own configuration (`config.rktd`) and many programs' saved data use it. Nothing in the file is run.
`.scrbl`	A Scribble document	Normally begins `#lang scribble/manual` or another `scribble/…` language. See Scribble.
`.rhm`	A Rhombus module	Begins `#lang rhombus`. See The #lang family.
`.zo`	Compiled code for one module	Written by `raco make` or on demand into a `compiled` folder beside the source, as `compiled/NAME_rkt.zo`. It is binary, not text; the viewer shows its bytes.
`.dep`	The dependencies of a compiled module	Written beside the `.zo` as `compiled/NAME_rkt.dep`: a record of the modules it depends on and the SHA-1 hash of the source, which `raco make` uses to decide what to rebuild.
`.ss`	Older module files	The extension of PLT Scheme; Racket still accepts it where the module's `#lang` line is given. The viewer chooses between Scheme and Racket by the first line (see SCM).

The name of a compiled file is made from the source name and extension: a source NAME.EXT becomes compiled/NAME_EXT.zo. A compiled file is used when it is not older than its source and its dependencies, unless the loader is told otherwise.

Encoding and line endings

Racket reads source as UTF-8; the reader works on characters, not bytes. The viewer shows a file that is not valid UTF-8 as Windows-1252.
A byte-order mark (U+FEFF) is treated like white space wherever a comment may stand. Since version 7.8.0.9 it is accepted before the #lang line.
A line ends with a linefeed, a carriage return, a carriage return with a linefeed, or (for the end of a ; comment) the Unicode next-line, line-separator and paragraph-separator characters. A string may contain a raw newline of any of those kinds; a backslash before the newline in a string removes it.
White space between tokens is any Unicode white-space character. Racket does not use indentation for meaning, but Rhombus does.

How a module begins

A module file starts with one of two things, after any comments or blank lines.

The #lang line

The usual start is #lang, one space, and the name of a language: a module path made of ASCII letters and digits, +, -, _ and /, which neither starts nor ends with /. The reader then hands the rest of the file to that language's reader. In a language written in S-expressions, #lang racket followed by the body is the same as (module name racket body …), where name comes from the file name without its directory and extension.

#lang racket

(provide fact)

(define (fact n)
  (if (zero? n) 1 (* n (fact (- n 1)))))

(module+ test
  (require rackunit)
  (check-equal? (fact 5) 120))

A module in #lang racket with a test submodule.

#! followed by a name that starts with an ASCII letter or digit, +, - or _ is a second spelling of #lang; it exists so that a program can start the way the language of another report requires (#!r6rs), and its use is discouraged elsewhere. Two languages are meta-languages that read a module path from the line: #lang s-exp MODULE-PATH uses the S-expressions that follow as the module body in the language MODULE-PATH, and #lang reader MODULE-PATH uses a reader module you name. #lang at-exp racket adds the @ notation of Scribble to a language that follows it on the line.

A module form

A file can instead hold a single (module name language body …) form with no #lang line. Racket reads it as it is; the #lang line is only a shorthand for it. A module read by racket file.rkt or require must be a module; a file of loose expressions is read with load, racket -f or the REPL.

Comments before the first line

A ; comment, a #| … |# block comment and a #; datum comment can all stand before #lang. A #! line comment (#! followed by a space or a /) may be the first line, so that a module can be a Unix script; such a comment continues to the next line if its line ends with a backslash.

#!/usr/bin/env racket
#lang racket/base
;; run with: chmod +x hello.rkt; ./hello.rkt
(displayln "hello")

A script with the interpreter line first.

Submodules, main and test

A module may contain modules. (module+ name body …) adds to a submodule that can see the enclosing module's names; (module* name language-or-#f body …) declares one that is read after the enclosing module and can import it. Two names have a use. A submodule called main runs when the file is run as a program (racket file.rkt), and not when it is required. A submodule called test is run by raco test, which is also what DrRacket's Run for tests uses. Both cost nothing when the module is required by other code. See Modules.

Running a file

Command	Effect
`racket hello.rkt`	Requires the module, runs its `main` submodule if it has one, and exits. Arguments after the file name are passed on in `current-command-line-arguments`.
`racket -t hello.rkt`	Requires the file; later flags are still read by `racket`.
`racket -l racket/base -e '(+ 1 2)'`	Requires a library by its `lib` path, then evaluates an expression and prints the result.
`racket -f x.rktl`	Loads the expressions in a file as if typed at the REPL.
`racket -i` (or no arguments)	Starts the REPL, after requiring `racket/init` unless a module-requiring flag came first.
`raco make x.rkt`	Compiles the module and everything it uses to `compiled/*.zo`.
`raco exe x.rkt`	Makes a stand-alone executable. See Packages and raco.

How the viewer reads these files

The viewer decides what a .rkt file is from its first lines: a module in a Racket language, a Typed Racket module (typed/racket), a Scribble document, a module with the @ notation (at-exp), a Rhombus module, a Datalog program, or a program in a teaching language. Each is shown with its own name and coloured by the matching scanner. .rktd files are coloured as data, .scrbl files as Scribble text, info.rkt is recognised by its name and .zo files are shown as bytes. A .ss or .scm file whose first line is #lang is shown as Racket. See Lexical structure for what each colour means.

Not described

Known, not yet covered

Reference: the byte layout of a .zo file and of a .dep file is not described. What the documentation says is that a compiled module is a linklet bundle (or, with submodules, a linklet directory) whose linklets are one per phase, plus metadata; in Racket CS the linklets are opaque machine code, and the layout changes between versions and virtual machines (the library that describes the structures, compiler/zo-structs, warns that they change incompatibly across versions). Viewer: a .zo file is shown as bytes, with a link to this page.
Reference: the -f flag is described from the Racket Guide; the full list of command-line flags of racket (the Racket Reference chapter on running) was not read in full.
Reference: the extension .rktl and its use for loaded code is a convention taken from how the tools use it; the documentation I read names no extension for load mode (its example is hi.rkts).

.RKT File Format – File structure