From 31bb2adfedbd47c296f902c28f8b3784cfaf4633 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20M=C3=BCller?= Date: Tue, 30 Jan 2024 14:30:18 +0100 Subject: [PATCH 1/3] Document builtin constants --- src/compiler/crystal/program.cr | 88 ++++++++++++++++++++++++--------- 1 file changed, 64 insertions(+), 24 deletions(-) diff --git a/src/compiler/crystal/program.cr b/src/compiler/crystal/program.cr index 936fc6a0a270..b7cf69c80bd7 100644 --- a/src/compiler/crystal/program.cr +++ b/src/compiler/crystal/program.cr @@ -278,33 +278,73 @@ module Crystal define_crystal_string_constant "BUILD_COMMIT", build_commit else define_crystal_nil_constant "BUILD_COMMIT" - end - - define_crystal_string_constant "BUILD_DATE", Crystal::Config.date - define_crystal_string_constant "CACHE_DIR", CacheDir.instance.dir - define_crystal_string_constant "DEFAULT_PATH", Crystal::Config.path - define_crystal_string_constant "DESCRIPTION", Crystal::Config.description - define_crystal_string_constant "PATH", Crystal::CrystalPath.default_path - define_crystal_string_constant "LIBRARY_PATH", Crystal::CrystalLibraryPath.default_path - define_crystal_string_constant "LIBRARY_RPATH", Crystal::CrystalLibraryPath.default_rpath - define_crystal_string_constant "VERSION", Crystal::Config.version - define_crystal_string_constant "LLVM_VERSION", Crystal::Config.llvm_version - define_crystal_string_constant "HOST_TRIPLE", Crystal::Config.host_target.to_s - define_crystal_string_constant "TARGET_TRIPLE", Crystal::Config.host_target.to_s - end - - private def define_crystal_string_constant(name, value) - define_crystal_constant name, StringLiteral.new(value).tap(&.set_type(string)) - end - - private def define_crystal_nil_constant(name) - define_crystal_constant name, NilLiteral.new.tap(&.set_type(self.nil)) - end - - private def define_crystal_constant(name, value) + end.doc = <<-MD + The build commit identifier of the Crystal compiler. + MD + + define_crystal_string_constant "BUILD_DATE", Crystal::Config.date, <<-MD + The build date of the Crystal compiler. + MD + define_crystal_string_constant "CACHE_DIR", CacheDir.instance.dir, <<-MD + 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. + MD + define_crystal_string_constant "DEFAULT_PATH", Crystal::Config.path, <<-MD + 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. + MD + define_crystal_string_constant "DESCRIPTION", Crystal::Config.description, <<-MD + Full version information of the Crystal compiler. Equivalent to `crystal --version`. + MD + define_crystal_string_constant "PATH", Crystal::CrystalPath.default_path, <<-MD + 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`. + MD + define_crystal_string_constant "LIBRARY_PATH", Crystal::CrystalLibraryPath.default_path, <<-MD + Colon-separated paths where the compiler searches for (binary) libraries. + + The value is defined by the environment variables `CRYSTAL_LIBRARY_PATH`. + MD + define_crystal_string_constant "LIBRARY_RPATH", Crystal::CrystalLibraryPath.default_rpath, <<-MD + Colon-separated paths where the loader searches for dynamic libraries at runtime. + + The value is defined by the environment variables `CRYSTAL_LIBRARY_RPATH`. + MD + define_crystal_string_constant "VERSION", Crystal::Config.version, <<-MD + The version of the Crystal compiler. + MD + define_crystal_string_constant "LLVM_VERSION", Crystal::Config.llvm_version, <<-MD + The version of LLVM used by the Crystal compiler. + MD + define_crystal_string_constant "HOST_TRIPLE", Crystal::Config.host_target.to_s, <<-MD + The LLVM target triple of the host system (the machine that the compiler runs on). + MD + define_crystal_string_constant "TARGET_TRIPLE", Crystal::Config.host_target.to_s, <<-MD + The LLVM target triple of the target system (the machine that the compiler builds for). + MD + end + + private def define_crystal_string_constant(name, value, doc = nil) + define_crystal_constant name, StringLiteral.new(value).tap(&.set_type(string)), doc + end + + private def define_crystal_nil_constant(name, doc = nil) + define_crystal_constant name, NilLiteral.new.tap(&.set_type(self.nil)), doc + end + + private def define_crystal_constant(name, value, doc = nil) : Const crystal.types[name] = const = Const.new self, crystal, name, value const.no_init_flag = true + if doc + const.doc = doc + end predefined_constants << const + const end property(target_machine : LLVM::TargetMachine) { codegen_target.to_target_machine } From 00de3a013ed324ea6a1a60ba0f0425c704d58e98 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20M=C3=BCller?= Date: Tue, 30 Jan 2024 15:14:23 +0100 Subject: [PATCH 2/3] Skip unless building docs --- src/compiler/crystal/program.cr | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/compiler/crystal/program.cr b/src/compiler/crystal/program.cr index b7cf69c80bd7..2b5dad09b1cc 100644 --- a/src/compiler/crystal/program.cr +++ b/src/compiler/crystal/program.cr @@ -340,7 +340,7 @@ module Crystal private def define_crystal_constant(name, value, doc = nil) : Const crystal.types[name] = const = Const.new self, crystal, name, value const.no_init_flag = true - if doc + if doc && wants_doc? const.doc = doc end predefined_constants << const From 7041fd66bf3726be4ca93cc8600c2af9cf5dce8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20M=C3=BCller?= Date: Tue, 30 Jan 2024 15:15:02 +0100 Subject: [PATCH 3/3] fixup --- src/compiler/crystal/program.cr | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/compiler/crystal/program.cr b/src/compiler/crystal/program.cr index 2b5dad09b1cc..675202ee0144 100644 --- a/src/compiler/crystal/program.cr +++ b/src/compiler/crystal/program.cr @@ -275,10 +275,11 @@ module Crystal # Defines a predefined constant in the Crystal module, such as BUILD_DATE and VERSION. private def define_crystal_constants if build_commit = Crystal::Config.build_commit - define_crystal_string_constant "BUILD_COMMIT", build_commit + build_commit_const = define_crystal_string_constant "BUILD_COMMIT", build_commit else - define_crystal_nil_constant "BUILD_COMMIT" - end.doc = <<-MD + build_commit_const = define_crystal_nil_constant "BUILD_COMMIT" + end + build_commit_const.doc = <<-MD if wants_doc? The build commit identifier of the Crystal compiler. MD