# module Crystal

##
Defined in:

crystal/datum.cr
crystal/dwarf.cr
crystal/dwarf/abbrev.cr
crystal/dwarf/info.cr
crystal/dwarf/line_numbers.cr
crystal/dwarf/strings.cr
crystal/mach_o.cr
crystal/main.cr
crystal/once.cr
crystal/print_buffered.cr
crystal/small_deque.cr
crystal/tracing.cr

##
Constant Summary

BUILD_COMMIT = `nil`

  The build commit identifier of the Crystal compiler.

BUILD_DATE = `"2025-07-25"`

  The build date of the Crystal compiler.

CACHE_DIR = `"/opt/local/var/macports/build/crystal-4cdec9b0/work/.home/.cache/crystal"`

  The cache directory configured for the Crystal compiler.

  The value is defined by the environment variable `CRYSTAL_CACHE_DIR` and defaults to the user's configured cache directory.

DEFAULT_PATH = `"$ORIGIN/../share/crystal/src"`

  The default Crystal path configured in the compiler. This value is baked into the compiler and usually points to the accompanying version of the standard library.

DESCRIPTION = `"Crystal 1.17.1 (2025-07-25)\n\nLLVM: 20.1.8\nDefault target: x86_64-apple-darwin20.6.0\n"`

  Full version information of the Crystal compiler. Equivalent to `crystal --version`.

HOST_TRIPLE = `"x86_64-apple-darwin20.6.0"`

  The LLVM target triple of the host system (the machine that the compiler runs on).

LIBRARY_PATH = `""`

  Colon-separated paths where the compiler searches for (binary) libraries.

  The value is defined by the environment variables `CRYSTAL_LIBRARY_PATH`.

LLVM_VERSION = `"20.1.8"`

  The version of LLVM used by the Crystal compiler.

PATH = `"./lib:/opt/local/var/macports/build/crystal-4cdec9b0/work/crystal-1.17.1/src"`

  Colon-separated paths where the compiler searches for required source files.

  The value is defined by the environment variable `CRYSTAL_PATH` and defaults to `DEFAULT_PATH`.

TARGET_TRIPLE = `"x86_64-apple-darwin20.6.0"`

  The LLVM target triple of the target system (the machine that the compiler builds for).

VERSION = `"1.17.1"`

  The version of the Crystal compiler.

##
Class Method Summary

- .main(&)

  Defines the main routine run by normal Crystal programs:

- .main(argc : Int32, argv : Pointer(Pointer(UInt8)))

  Main method run by all Crystal programs at startup.

- .main_user_code(argc : Int32, argv : Pointer(Pointer(UInt8)))

  Executes the main user code.

- .print_buffered(message : String, *args, to io : IO, exception = nil, backtrace = nil) : Nil

  Prepares an error message, with an optional exception or backtrace, to an in-memory buffer, before writing to an IO, usually STDERR, in a single write operation.

- .print_error_buffered(message : String, *args, exception = nil, backtrace = nil) : Nil

  Identical to `#print_buffered` but eventually calls `System.print_error(bytes)` to write to stderr without going through the event loop.

- .trace(section : Tracing::Section, operation : String, time : UInt64 | Nil = nil, **metadata, &)
- .trace(section : Tracing::Section, operation : String, time : UInt64 | Nil = nil, **metadata)

##
Class Method Detail

def self.main(&) #

Defines the main routine run by normal Crystal programs:

- Initializes runtime requirements (GC, ...)
- Invokes the given block
- Handles unhandled exceptions
- Invokes `at_exit` handlers
- Flushes `STDOUT` and `STDERR`

This method can be invoked if you need to define a custom main (as in C main) function, doing all the above steps.

For example:

    fun main(argc : Int32, argv : UInt8**) : Int32
      Crystal.main do
        elapsed = Time.measure do
          Crystal.main_user_code(argc, argv)
        end
        puts "Time to execute program: #{elapsed}"
      end
    end

Note that the above is really just an example, almost the same can be accomplished with `at_exit`. But in some cases redefinition of C's main is needed.

def self.main(argc : Int32, argv : Pointer(Pointer(UInt8))) #

Main method run by all Crystal programs at startup.

This setups up the GC, invokes your program, rescuing any handled exception, and then runs `at_exit` handlers.

This method is automatically invoked for you, so you don't need to invoke it.

However, if you need to define a special main C function, you can redefine main and invoke `Crystal.main` from it:

    fun main(argc : Int32, argv : UInt8**) : Int32
      # some setup before Crystal main
      Crystal.main(argc, argv)
      # some cleanup logic after Crystal main
    end

The `Crystal.main` can also be passed as a callback:

    fun main(argc : Int32, argv : UInt8**) : Int32
      LibFoo.init_foo_and_invoke_main(argc, argv, ->Crystal.main(Int32, UInt8**))
    end

Note that before `Crystal.main` is invoked the GC is not setup yet, so nothing that allocates memory in Crystal (like `new` for classes) can be used.

def self.main_user_code(argc : Int32, argv : Pointer(Pointer(UInt8))) #

Executes the main user code. This normally is executed after initializing the GC and before executing `at_exit` handlers.

You should never invoke this method unless you need to redefine C's main function. See `Crystal.main` for more details.

def self.print_buffered(message : String, *args, to io : IO, exception = nil, backtrace = nil) : Nil #

Prepares an error message, with an optional exception or backtrace, to an in-memory buffer, before writing to an IO, usually STDERR, in a single write operation.

Avoids intermingled messages caused by multiple threads writing to a STDIO in parallel. This may still happen, since writes may not be atomic when the overall size is larger than PIPE_BUF, buf it should at least write 512 bytes atomically.

def self.print_error_buffered(message : String, *args, exception = nil, backtrace = nil) : Nil #

Identical to `#print_buffered` but eventually calls `System.print_error(bytes)` to write to stderr without going through the event loop.

def self.trace(section : Tracing::Section, operation : String, time : UInt64 | Nil = nil, **metadata, &) #
def self.trace(section : Tracing::Section, operation : String, time : UInt64 | Nil = nil, **metadata) #