Skip to content

AGENTS.md

Latest commit

 

History

History
72 lines (48 loc) · 3.39 KB

AGENTS.md

File metadata and controls

72 lines (48 loc) · 3.39 KB
Raw

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Important:

  • All AI-assisted contributions, including code, PR/issue descriptions, comments, and code reviews, must comply with the LLM usage policy . Important: state LLM usage clearly in descriptions, commit messages, etc.
  • Read CONTRIBUTING.md, in particular the "Forbidden" section!

Project Overview

Dotty is the Scala 3 compiler (dotc). It compiles Scala source code into JVM bytecode (and optionally Scala.js IR). The compiler is itself written in Scala 3.

We care about maintainability. "The tests pass" is not enough to justify that a change is good.

Build Commands

Use sbt --client (sbt with native thin client) to run commands. This keeps an sbt server running for faster subsequent invocations.

Compilation

  • sbt --client scalac <file> - Compile a file with the current compiler changes
  • sbt --client scala <class> - Run a compiled class

Use the local/ directory for temporary test files (gitignored).

Testing

  • sbt --client testCompilation - Run the whole compilation test suite.
  • sbt --client testCompilation <name> - Run compilation tests matching <name> (e.g., sbt --client testCompilation i12345)
  • sbt --client scala3-bootstrapped/test - Run all tests (slow, CI-level)
  • sbt --client "testCompilation --update-checkfiles" - Update .check files with actual output

Test Directory Structure

Tests are in tests/ with categories:

  • tests/pos - Should compile successfully
  • tests/neg - Should fail to compile (requires // error annotations on expected error lines)
  • tests/run - Compile and execute (requires @main def Test or object Test extends App)
  • tests/pos-custom-args, tests/neg-custom-args - Tests requiring special compiler options

Custom compiler options can be specified:

  1. Per-directory in compiler/test/dotty/tools/dotc/CompilationTests.scala
  2. Per-file with //> using options <flags> directive at the top of the file

Capture checking tests are in tests/{pos,neg}-custom-args/captures. Use -Ycc-verbose for verbose capture checking output.

Multi-file tests: Use _1.scala, _2.scala suffixes for ordered separate compilation, or no suffix for joint compilation.

Checkfiles: <test>.check files contain expected compiler output or program output.

Test annotations (magic comments):

  • // error - Expect an error on this line (use multiple times for multiple errors)
  • // warn - Expect a warning on this line
  • // nopos-error - Expect an error with no position (can be anywhere in file)
  • // anypos-error - Expect an error with position that can't be annotated
  • // scalajs: --skip - Skip this test for Scala.js

Bootstrapping

The compiler has two configurations:

  • nonbootstrapped - Built with a released Scala 3 compiler (faster iteration)
  • bootstrapped - Built with itself (required for some tests, final validation)

Use scala3-compiler-bootstrapped/testCompilation for tests requiring the bootstrapped compiler.

Documentation

Documentation lives in docs/_docs/:

  • docs/_docs/reference/ - Scala 3 language reference
  • docs/_docs/reference/experimental/capture-checking/ - Capture checking specification
  • docs/_docs/internals/ - Compiler internals documentation

For available AI-assisted documentation workflows or skills start refer to ./docs/.ai/INDEX.md