diff --git a/Makefile b/Makefile index 00fb74ae5386..efaae77a7d88 100644 --- a/Makefile +++ b/Makefile @@ -41,6 +41,7 @@ deref_symlinks ?= ## Deference symbolic links for `make install` O := .build SOURCES := $(shell find src -name '*.cr') SPEC_SOURCES := $(shell find spec -name '*.cr') +MAN1PAGES := $(patsubst doc/man/%.adoc,man/%.1,$(wildcard doc/man/*.adoc)) override FLAGS += -D strict_multi_assign -D preview_overload_order $(if $(release),--release )$(if $(stats),--stats )$(if $(progress),--progress )$(if $(threads),--threads $(threads) )$(if $(debug),-d )$(if $(static),--static )$(if $(LDFLAGS),--link-flags="$(LDFLAGS)" )$(if $(target),--cross-compile --target $(target) )$(if $(interpreter),,-Dwithout_interpreter ) SPEC_WARNINGS_OFF := --exclude-warnings spec/std --exclude-warnings spec/compiler --exclude-warnings spec/primitives override SPEC_FLAGS += $(if $(verbose),-v )$(if $(junit_output),--junit_output $(junit_output) )$(if $(order),--order=$(order) ) @@ -253,10 +254,12 @@ $(LLVM_EXT_OBJ): $(LLVM_EXT_DIR)/llvm_ext.cc $(call check_llvm_config) $(CXX) -c $(CXXFLAGS) -o $@ $< $(shell $(LLVM_CONFIG) --cxxflags) +man/: $(MAN1PAGES) + man/%.gz: man/% gzip -c -9 $< > $@ -man/crystal.1: doc/man/crystal.adoc +man/%.1: doc/man/%.adoc SOURCE_DATE_EPOCH=$(SOURCE_DATE_EPOCH) asciidoctor -a crystal_version=$(CRYSTAL_VERSION) $< -b manpage -o $@ .PHONY: clean diff --git a/doc/man/crystal-build.adoc b/doc/man/crystal-build.adoc new file mode 100644 index 000000000000..5b0d5e3c0844 --- /dev/null +++ b/doc/man/crystal-build.adoc @@ -0,0 +1,104 @@ += crystal-build(1) +:doctype: manpage +:date: {localdate} +:crystal_version: {crystal_version} +:man manual: Crystal Compiler Command Line Reference Guide +:man source: crystal {crystal_version} + +== Name +crystal-build - Compile a Crystal program + +== Synopsis +*crystal build* [options] [programfile] [--] [arguments] + +== Options + +*--cross-compile*:: +Generate an object file for cross compilation and prints the command to build the executable. The object file should be copied +to the target system and the printed command should be executed +there. This flag mainly exists for porting the compiler to new +platforms, where possible run the compiler on the target platform +directly. +*-d*, *--debug*:: +Generate the output with symbolic debug symbols. These are read +when debugging the built program with tools like lldb, gdb, valgrind etc. and provide mappings to the original source code for +those tools. +*--no-debug*:: +Generate the output without any symbolic debug symbols. +*-D* _FLAG_, *--define* _FLAG_:: +Define a compile-time flag. This is useful to conditionally define types, methods, or commands based on flags available at compile time. The default flags are from the target triple given +with *--target-triple* or the hosts default, if none is given. +*--emit* [asm|llvm-bc|llvm-ir|obj]:: +Comma separated list of types of output for the compiler to emit. +You can use this to see the generated LLVM IR, LLVM bitcode, assembly, and object files. +*--frame-pointers* [auto|always|non-leaf]:: +Control the preservation of frame pointers. The default value, +`--frame-pointers=auto`, will preserve frame pointers on debug +builds and try to omit them on release builds (certain platforms +require them to stay enabled). `--frame-pointers=always` will always preserve them, and non-leaf will only force their preservation on non-leaf functions. +*-f* text|json, *--format* text|json:: +Format of output. Defaults to text. The json format can be used +to get a more parser-friendly output. +*--error-trace*:: +Show full error trace. +*--ll*:: Dump LLVM assembly file to output directory. +*--link-flags* _FLAGS_:: +Pass additional flags to the linker. Though you can specify those +flags on the source code, this is useful for passing environment +specific information directly to the linker, like non-standard +library paths or names. For more information on specifying linker +flags on source, you can read the "C bindings" section of the +documentation available on the official web site. +*--mcpu* _CPU_:: +Specify a specific CPU to generate code for. This will pass a +-mcpu flag to LLVM, and is only intended to be used for cross- +compilation. For a list of available CPUs, invoke "llvm-as < +/dev/null | llc -march=xyz -mcpu=help". Passing --mcpu native +will pass the host CPU name to tune performance for the host. +*--mattr* _CPU_:: +Override or control specific attributes of the target, such as +whether SIMD operations are enabled or not. The default set of +attributes is set by the current CPU. This will pass a -mattr +flag to LLVM, and is only intended to be used for cross-compilation. For a list of available attributes, invoke "llvm-as < +/dev/null | llc -march=xyz -mattr=help". +*--mcmodel* default|kernel|small|medium|large:: +Specifies a specific code model to generate code for. This will +pass a --code-model flag to LLVM. +*--no-color*:: +Disable colored output. +*--no-codegen*:: +Don't do code generation, just parse the file. +*-o*:: Specify filename of output. +*--prelude*:: +Specify prelude to use. The default one initializes the garbage +collector. You can also use --prelude=empty to use no preludes. +This can be useful for checking code generation for a specific +source code file. +*-O* _LEVEL_:: Optimization mode: 0 (default), 1, 2, 3. See *OPTIMIZATIONS* for +details. +*--release*:: +Compile in release mode. Equivalent to *-O3 --single-module* +*--error-trace*:: +Show full stack trace. Disabled by default, as the full trace +usually makes error messages less readable and not always deliver +relevant information. +*-s*, *--stats*:: +Print statistics about the different compiler stages for the current build. Output time and used memory for each compiler process. +*-p*, *--progress*:: +Print statistics about the progress for the current build. +*-t*, *--time*:: +Print statistics about the execution time. +*--single-module*:: +Generate a single LLVM module. By default, one LLVM module is +created for each type in a program. *--release* implies this option. +*--threads* _NUM_:: +Maximum number of threads to use for code generation. The default +is 8 threads. +*--target* _TRIPLE_:: +Enable target triple; intended to use for cross-compilation. See +llvm documentation for more information about target triple. +*--verbose*:: +Display the commands executed by the system. +*--static*:: Create a statically linked executable. +*--stdin-filename* _FILENAME_:: +Source file name to be read from STDIN. diff --git a/doc/man/crystal-docs.adoc b/doc/man/crystal-docs.adoc new file mode 100644 index 000000000000..fe5751580ec4 --- /dev/null +++ b/doc/man/crystal-docs.adoc @@ -0,0 +1,65 @@ += crystal-docs(1) +:doctype: manpage +:date: {localdate} +:crystal_version: {crystal_version} +:man manual: Crystal Compiler Command Line Reference Guide +:man source: crystal {crystal_version} + +== Name +crystal-doc - Generate API docs for Crystal code + +== Synopsis +*crystal build* [options] [programfile] [--] [arguments] + +== Description + +Generate documentation from comments using a subset of markdown. The output +is saved in html format on the created docs/ folder. More information about +documentation conventions can be found at . + +== Options + +*--project-name* _NAME_:: +Set the project name. The default value is extracted from +shard.yml if available. ++ +In case no default can be found, this option is mandatory. +*--project-version* _VERSION_:: +Set the project version. The default value is extracted from current git commit or shard.yml if available. ++ +In case no default can be found, this option is mandatory. +*--json-config-url* _URL_:: +Set the URL pointing to a config file (used for discovering versions). +*--source-refname* _REFNAME_:: +Set source refname (e.g. git tag, commit hash). The default value +is extracted from current git commit if available. ++ +If this option is missing and can't be automatically determined, +the generator can't produce source code links. +*--source-url-pattern* _URL_:: +Set URL pattern for source code links. The default value is extracted from git remotes ("origin" or first one) if available and +the provider's URL pattern is recognized. ++ +Supported replacement tags: ++ +-- +*%{refname}*:: commit reference +*%{path}*:: path to source file inside the repository +*%{filename}*:: + basename of the source file +*%{line}*:: line number +-- ++ +If this option is missing and can't be automatically determined, +the generator can't produce source code links. +*-o* _DIR_, *--output* _DIR_:: +Set the output directory (default: ./docs). +*-b* _URL_, **--canonical-base-url** _URL_:: +Indicate the preferred URL with rel="canonical" link element. +*-b* _URL_, *--sitemap-base-url* _URL_:: +Set the sitemap base URL. Sitemap will only be generated when +this option is set. +*--sitemap-priority* _PRIO_:: +Set the priority assigned to sitemap entries (default: 1.0). +*--sitemap-changefreq* _FREQ_:: +Set the changefreq assigned to sitemap entries (default: never). diff --git a/doc/man/crystal-env.adoc b/doc/man/crystal-env.adoc new file mode 100644 index 000000000000..25428ed9c8bc --- /dev/null +++ b/doc/man/crystal-env.adoc @@ -0,0 +1,40 @@ += crystal-env(1) +:doctype: manpage +:date: {localdate} +:crystal_version: {crystal_version} +:man manual: Crystal Compiler Command Line Reference Guide +:man source: crystal {crystal_version} + +== Name +crystal-env - Print environment variables for the Crystal compiler + +== Synopsis +*crystal env* [variables] + +== Description + +Print Crystal-specific environment variables in a format compatible with +shell scripts. If one or more variable names are given as arguments, it +prints only the value of each named variable on its own line. + +Variables: + +*CRYSTAL_CACHE_DIR*:: +Please see ENVIRONMENT VARIABLES. + +*CRYSTAL_LIBRARY_PATH*:: +Please see ENVIRONMENT VARIABLES. + +*CRYSTAL_PATH*:: +Please see ENVIRONMENT VARIABLES. + +*CRYSTAL_VERSION*:: +Contains Crystal version. + +== Informative Variables + +These variables expose information about the Crystal compiler and cannot be configured externally. + +=== CRYSTAL_VERSION + +Contains Crystal version. diff --git a/doc/man/crystal-eval.adoc b/doc/man/crystal-eval.adoc new file mode 100644 index 000000000000..6daade80ab0b --- /dev/null +++ b/doc/man/crystal-eval.adoc @@ -0,0 +1,42 @@ += crystal-eval(1) +:doctype: manpage +:date: {localdate} +:crystal_version: {crystal_version} +:man manual: Crystal Compiler Command Line Reference Guide +:man source: crystal {crystal_version} + +== Name +crystal-eval - Evaluate a crystal program + +== Synopsis +*crystal eval* [options] [source] + +== Description + +Evaluate code from arguments or, if no arguments are passed, from the standard input. Useful for experiments. + +== Options + +*-d*, *--debug*:: +Generate the output with symbolic debug symbols. These are read +when debugging the built program with tools like lldb, gdb, valgrind etc. and provide mappings to the original source code for +those tools. +*--no-debug*:: +Generate the output without any symbolic debug symbols. +*-D* _FLAG_, *--define* _FLAG_:: +Define a compile-time flag. This is useful to conditionally define types, methods, or commands based on flags available at compile time. The default flags are from the target triple given +with --target-triple or the hosts default, if none is given. +*--error-trace*:: +Show full error trace. +*-O* _LEVEL_:: Optimization mode: 0 (default), 1, 2, 3. See *OPTIMIZATIONS* for details. +*--release*:: +Compile in release mode. Equivalent to *-O3 --single-module* +*-s*, *--stats*:: +Print statistics about the different compiler stages for the current build. Output time and used memory for each compiler +process. +*-p*, *--progress*:: +Print statistics about the progress for the current build. +*-t*, *--time*:: +Print statistics about the execution time. +*--no-color*:: +Disable colored output. diff --git a/doc/man/crystal-init.adoc b/doc/man/crystal-init.adoc new file mode 100644 index 000000000000..7a475aa00d8b --- /dev/null +++ b/doc/man/crystal-init.adoc @@ -0,0 +1,30 @@ += crystal-init(1) +:doctype: manpage +:date: {localdate} +:crystal_version: {crystal_version} +:man manual: Crystal Compiler Command Line Reference Guide +:man source: crystal {crystal_version} + +== Name +crystal-init - Create a a new Crystal project + +== Synopsis +*crystal init* TYPE [DIR | NAME DIR] + +== Description + +TYPE is one of: + +*lib* Creates a library skeleton + +*app* Creates an application skeleton + +This initializes the lib/app project folder as a git repository, with a license file, a README file, a shard.yml for use with shards (the Crystal dependency manager), a .gitignore file, and src and spec folders. + +DIR - directory where project will be generated + +NAME - name of project to be generated (default: basename of DIR) + +== Options + +*-f, --force*:: Force overwrite existing files. +*-s, --skip-existing*:: Skip existing files. diff --git a/doc/man/crystal-play.adoc b/doc/man/crystal-play.adoc new file mode 100644 index 000000000000..68f07153525f --- /dev/null +++ b/doc/man/crystal-play.adoc @@ -0,0 +1,25 @@ += crystal-play(1) +:doctype: manpage +:date: {localdate} +:crystal_version: {crystal_version} +:man manual: Crystal Compiler Command Line Reference Guide +:man source: crystal {crystal_version} + +== Name +crystal-play - Run the Crystal playground + +== Synopsis +*crystal play* [options] [file] + +== Description + +Starts the *crystal* playground server on port 8080, by default. + +== Options + +*-p* _PORT_, *--port* _PORT_:: +Run the playground on the specified port. Default is 8080. +*-b* _HOST_, *--binding* _HOST_:: +Bind the playground to the specified IP. +*-v*, *--verbose*:: +Display detailed information of the executed code. diff --git a/doc/man/crystal-run.adoc b/doc/man/crystal-run.adoc new file mode 100644 index 000000000000..6a9e25ef7956 --- /dev/null +++ b/doc/man/crystal-run.adoc @@ -0,0 +1,20 @@ += crystal-run(1) +:doctype: manpage +:date: {localdate} +:crystal_version: {crystal_version} +:man manual: Crystal Compiler Command Line Reference Guide +:man source: crystal {crystal_version} + +== Name +crystal-run - Compile and run a Crystal program + +== Synopsis +*crystal run* [options] [programfile] [--] [arguments] + +== Description + +The default command. Compile and run program. + +== Options + +Same as the build options. diff --git a/doc/man/crystal-spec.adoc b/doc/man/crystal-spec.adoc new file mode 100644 index 000000000000..7bc4eac5a603 --- /dev/null +++ b/doc/man/crystal-spec.adoc @@ -0,0 +1,38 @@ += crystal-spec(1) +:doctype: manpage +:date: {localdate} +:crystal_version: {crystal_version} +:man manual: Crystal Compiler Command Line Reference Guide +:man source: crystal {crystal_version} + +== Name +crystal-spec - Compile and run Crystal spec files + +== Synopsis +*crystal spec* [options] [files] + +== Options + +*-d*, *--debug*:: +Generate the output with symbolic debug symbols. These are read +when debugging the built program with tools like lldb, gdb, valgrind etc. and provide mappings to the original source code for +those tools. +*--no-debug*:: +Generate the output without any symbolic debug symbols. +*-D* _FLAG_, *--define* _FLAG_:: +Define a compile-time flag. This is useful to conditionally define types, methods, or commands based on flags available at compile time. The default flags are from the target triple given +with *--target-triple* or the hosts default, if none is given. +*--error-trace*:: +Show full error trace. +*-O* _LEVEL_:: Optimization mode: 0 (default), 1, 2, 3. See *OPTIMIZATIONS* for details. +*--release*:: +Compile in release mode. Equivalent to *-O3 --single-module* +*-s*, *--stats*:: +Print statistics about the different compiler stages for the current build. Output time and used memory for each compiler +process. +*-p*, *--progress*:: +Print statistics about the progress for the current build. +*-t*, *--time*:: +Print statistics about the execution time. +*--no-color*:: +Disable colored output. diff --git a/doc/man/crystal-tool-dependencies.adoc b/doc/man/crystal-tool-dependencies.adoc new file mode 100644 index 000000000000..972cef5216cc --- /dev/null +++ b/doc/man/crystal-tool-dependencies.adoc @@ -0,0 +1,35 @@ += crystal-tool-dependencies(1) +:doctype: manpage +:date: {localdate} +:crystal_version: {crystal_version} +:man manual: Crystal Compiler Command Line Reference Guide +:man source: crystal {crystal_version} + +== Name +crystal-tool-dependencies - Show tree of required source files. + +== Synopsis +*crystal tool dependencies* [options] [programfile] + +== Options + +*-D* _FLAG_, *--define*=_FLAG_:: + Define a compile-time flag. This is useful to con ditionally define types, methods, or commands based + on flags available at compile time. The default + flags are from the target triple given with *--tar* get-triple or the hosts default, if none is given. +*-f* _FORMAT_, *--format*=_FORMAT_:: + Output format 'tree' (default), 'flat', 'dot', or + 'mermaid'. +*-i* _PATH_, *--include*=_PATH_:: + Include path in output. +*-e* _PATH_, *--exclude*=_PATH_:: + Exclude path in output. +*--error-trace*:: + Show full error trace. +*--prelude*:: + Specify prelude to use. The default one initializes + the garbage collector. You can also use *--pre* lude=empty to use no preludes. This can be useful + for checking code generation for a specific source + code file. +*--verbose*:: + Show skipped and heads of filtered paths diff --git a/doc/man/crystal-tool-format.adoc b/doc/man/crystal-tool-format.adoc new file mode 100644 index 000000000000..36046761f439 --- /dev/null +++ b/doc/man/crystal-tool-format.adoc @@ -0,0 +1,21 @@ += crystal-tool-format(1) +:doctype: manpage +:date: {localdate} +:crystal_version: {crystal_version} +:man manual: Crystal Compiler Command Line Reference Guide +:man source: crystal {crystal_version} + +== Name +crystal-tool-format - Format Crystal source files + +== Synopsis +*crystal tool format* [options] [source...] + +== Description + +Format project, directories and/or files with the coding +style used in the standard library. + +== Options + +*--check*:: Only check conformity but do not apply any changes. diff --git a/doc/man/crystal-tool-unreachable.adoc b/doc/man/crystal-tool-unreachable.adoc new file mode 100644 index 000000000000..ffa22784e344 --- /dev/null +++ b/doc/man/crystal-tool-unreachable.adoc @@ -0,0 +1,46 @@ += crystal-tool-unreachable(1) +:doctype: manpage +:date: {localdate} +:crystal_version: {crystal_version} +:man manual: Crystal Compiler Command Line Reference Guide +:man source: crystal {crystal_version} + +== Name +crystal-tool-unreachable - Identify methods that are never called + +== Synopsis +*crystal tool unreachable* [options] [source...] + +== Description + +Show methods that are never called. The text output is a list +of lines with columns separated by tab. + +Output fields: + +*count*:: sum of all calls to this method (only with *--tallies* option; otherwise skipped) +*location*:: pathname, line and column, all separated by colon name +*lines*:: length of the def in lines annotations + +== Options + +*-D* _FLAG_, *--define*=_FLAG_:: + Define a compile-time flag. This is useful to con ditionally define types, + methods, or commands based on flags available at compile time. The default + flags are from the target triple given with *--target-triple* or the hosts + default, if none is given. +*-f* _FORMAT_, *--format*=_FORMAT_:: + Output format 'text' (default), 'json', 'codecov', or 'csv'. +*--tallies*:: + Print reachable methods and their call counts as well. +*--check*:: Exit with error if there is any unreachable code. +*-i* _PATH_, *--include*=_PATH_:: + Include path in output. +*-e* _PATH_, *--exclude*=_PATH_:: + Exclude path in output (default: lib). +*--error-trace*:: + Show full error trace. +*--prelude*:: + Specify prelude to use. The default one initializes the garbage collector. You + can also use *--prelude=empty* to use no preludes. This can be useful for + checking code generation for a specific source code file. diff --git a/doc/man/crystal.adoc b/doc/man/crystal.adoc index 40d0b5609450..701d0d6dd195 100644 --- a/doc/man/crystal.adoc +++ b/doc/man/crystal.adoc @@ -50,398 +50,64 @@ The optimizations are not turned on by default because the compile times are muc faster without them and the performance of the program is still pretty good without them, so it allows to use the *crystal* command almost to be used as if it was an interpreter. -== Options -The *crystal* command accepts the following options - -=== init - -*init* TYPE [DIR | NAME DIR] - -Generates a new Crystal project. - -TYPE is one of: - -*lib* Creates a library skeleton + -*app* Creates an application skeleton - -This initializes the lib/app project folder as a git repository, with a license file, a README file, a shard.yml for use with shards (the Crystal dependency manager), a .gitignore file, and src and spec folders. - -DIR - directory where project will be generated - -NAME - name of project to be generated (default: basename of DIR) - -Options: - -*-f, --force*:: Force overwrite existing files. -*-s, --skip-existing*:: Skip existing files. - -=== build - -*build* [options] [programfile] [--] [arguments] - -Compile program. - -Options: - -*--cross-compile*:: -Generate an object file for cross compilation and prints the command to build the executable. The object file should be copied -to the target system and the printed command should be executed -there. This flag mainly exists for porting the compiler to new -platforms, where possible run the compiler on the target platform -directly. -*-d*, *--debug*:: -Generate the output with symbolic debug symbols. These are read -when debugging the built program with tools like lldb, gdb, valgrind etc. and provide mappings to the original source code for -those tools. -*--no-debug*:: -Generate the output without any symbolic debug symbols. -*-D* _FLAG_, *--define* _FLAG_:: -Define a compile-time flag. This is useful to conditionally define types, methods, or commands based on flags available at compile time. The default flags are from the target triple given -with *--target-triple* or the hosts default, if none is given. -*--emit* [asm|llvm-bc|llvm-ir|obj]:: -Comma separated list of types of output for the compiler to emit. -You can use this to see the generated LLVM IR, LLVM bitcode, assembly, and object files. -*--frame-pointers* [auto|always|non-leaf]:: -Control the preservation of frame pointers. The default value, -`--frame-pointers=auto`, will preserve frame pointers on debug -builds and try to omit them on release builds (certain platforms -require them to stay enabled). `--frame-pointers=always` will always preserve them, and non-leaf will only force their preservation on non-leaf functions. -*-f* text|json, *--format* text|json:: -Format of output. Defaults to text. The json format can be used -to get a more parser-friendly output. -*--error-trace*:: -Show full error trace. -*--ll*:: Dump LLVM assembly file to output directory. -*--link-flags* _FLAGS_:: -Pass additional flags to the linker. Though you can specify those -flags on the source code, this is useful for passing environment -specific information directly to the linker, like non-standard -library paths or names. For more information on specifying linker -flags on source, you can read the "C bindings" section of the -documentation available on the official web site. -*--mcpu* _CPU_:: -Specify a specific CPU to generate code for. This will pass a --mcpu flag to LLVM, and is only intended to be used for cross- -compilation. For a list of available CPUs, invoke "llvm-as < -/dev/null | llc -march=xyz -mcpu=help". Passing --mcpu native -will pass the host CPU name to tune performance for the host. -*--mattr* _CPU_:: -Override or control specific attributes of the target, such as -whether SIMD operations are enabled or not. The default set of -attributes is set by the current CPU. This will pass a -mattr -flag to LLVM, and is only intended to be used for cross-compilation. For a list of available attributes, invoke "llvm-as < -/dev/null | llc -march=xyz -mattr=help". -*--mcmodel* default|kernel|small|medium|large:: -Specifies a specific code model to generate code for. This will -pass a --code-model flag to LLVM. -*--no-color*:: -Disable colored output. -*--no-codegen*:: -Don't do code generation, just parse the file. -*-o*:: Specify filename of output. -*--prelude*:: -Specify prelude to use. The default one initializes the garbage -collector. You can also use --prelude=empty to use no preludes. -This can be useful for checking code generation for a specific -source code file. -*-O* _LEVEL_:: Optimization mode: 0 (default), 1, 2, 3. See *OPTIMIZATIONS* for -details. -*--release*:: -Compile in release mode. Equivalent to *-O3 --single-module* -*--error-trace*:: -Show full stack trace. Disabled by default, as the full trace -usually makes error messages less readable and not always deliver -relevant information. -*-s*, *--stats*:: -Print statistics about the different compiler stages for the current build. Output time and used memory for each compiler process. -*-p*, *--progress*:: -Print statistics about the progress for the current build. -*-t*, *--time*:: -Print statistics about the execution time. -*--single-module*:: -Generate a single LLVM module. By default, one LLVM module is -created for each type in a program. *--release* implies this option. -*--threads* _NUM_:: -Maximum number of threads to use for code generation. The default -is 8 threads. -*--target* _TRIPLE_:: -Enable target triple; intended to use for cross-compilation. See -llvm documentation for more information about target triple. -*--verbose*:: -Display the commands executed by the system. -*--static*:: Create a statically linked executable. -*--stdin-filename* _FILENAME_:: -Source file name to be read from STDIN. - -=== docs - -Generate documentation from comments using a subset of markdown. The output -is saved in html format on the created docs/ folder. More information about -documentation conventions can be found at . - -Options: - -*--project-name* _NAME_:: -Set the project name. The default value is extracted from -shard.yml if available. -+ -In case no default can be found, this option is mandatory. -*--project-version* _VERSION_:: -Set the project version. The default value is extracted from current git commit or shard.yml if available. -+ -In case no default can be found, this option is mandatory. -*--json-config-url* _URL_:: -Set the URL pointing to a config file (used for discovering versions). -*--source-refname* _REFNAME_:: -Set source refname (e.g. git tag, commit hash). The default value -is extracted from current git commit if available. -+ -If this option is missing and can't be automatically determined, -the generator can't produce source code links. -*--source-url-pattern* _URL_:: -Set URL pattern for source code links. The default value is extracted from git remotes ("origin" or first one) if available and -the provider's URL pattern is recognized. -+ -Supported replacement tags: -+ --- -*%{refname}*:: commit reference -*%{path}*:: path to source file inside the repository -*%{filename}*:: - basename of the source file -*%{line}*:: line number --- -+ -If this option is missing and can't be automatically determined, -the generator can't produce source code links. -*-o* _DIR_, *--output* _DIR_:: -Set the output directory (default: ./docs). -*-b* _URL_, **--canonical-base-url** _URL_:: -Indicate the preferred URL with rel="canonical" link element. -*-b* _URL_, *--sitemap-base-url* _URL_:: -Set the sitemap base URL. Sitemap will only be generated when -this option is set. -*--sitemap-priority* _PRIO_:: -Set the priority assigned to sitemap entries (default: 1.0). -*--sitemap-changefreq* _FREQ_:: -Set the changefreq assigned to sitemap entries (default: never). - -=== env -*env* [variables] - -Print Crystal-specific environment variables in a format compatible with -shell scripts. If one or more variable names are given as arguments, it -prints only the value of each named variable on its own line. - -Variables: - --- -*CRYSTAL_CACHE_DIR*:: -Please see ENVIRONMENT VARIABLES. - -*CRYSTAL_LIBRARY_PATH*:: -Please see ENVIRONMENT VARIABLES. - -*CRYSTAL_PATH*:: -Please see ENVIRONMENT VARIABLES. - -*CRYSTAL_VERSION*:: -Contains Crystal version. --- - -=== eval -*eval* [options] [source] - -Evaluate code from arguments or, if no arguments are passed, from the standard input. Useful for experiments. - -Options: - -*-d*, *--debug*:: -Generate the output with symbolic debug symbols. These are read -when debugging the built program with tools like lldb, gdb, valgrind etc. and provide mappings to the original source code for -those tools. -*--no-debug*:: -Generate the output without any symbolic debug symbols. -*-D* _FLAG_, *--define* _FLAG_:: -Define a compile-time flag. This is useful to conditionally define types, methods, or commands based on flags available at compile time. The default flags are from the target triple given -with --target-triple or the hosts default, if none is given. -*--error-trace*:: -Show full error trace. -*-O* _LEVEL_:: Optimization mode: 0 (default), 1, 2, 3. See *OPTIMIZATIONS* for details. -*--release*:: -Compile in release mode. Equivalent to *-O3 --single-module* -*-s*, *--stats*:: -Print statistics about the different compiler stages for the current build. Output time and used memory for each compiler -process. -*-p*, *--progress*:: -Print statistics about the progress for the current build. -*-t*, *--time*:: -Print statistics about the execution time. -*--no-color*:: -Disable colored output. - -=== play -*play* [options] [file] - -Starts the *crystal* playground server on port 8080, by default. - -Options: - -*-p* _PORT_, *--port* _PORT_:: -Run the playground on the specified port. Default is 8080. -*-b* _HOST_, *--binding* _HOST_:: -Bind the playground to the specified IP. -*-v*, *--verbose*:: -Display detailed information of the executed code. - -=== run -*run* [options] [programfile] [--] [arguments] - -The default command. Compile and run program. - -Options: Same as the build options. - -=== spec -spec [options] [files] - -Compile and run specs (in spec directory). - -Options: - -*-d*, *--debug*:: -Generate the output with symbolic debug symbols. These are read -when debugging the built program with tools like lldb, gdb, valgrind etc. and provide mappings to the original source code for -those tools. -*--no-debug*:: -Generate the output without any symbolic debug symbols. -*-D* _FLAG_, *--define* _FLAG_:: -Define a compile-time flag. This is useful to conditionally define types, methods, or commands based on flags available at compile time. The default flags are from the target triple given -with *--target-triple* or the hosts default, if none is given. -*--error-trace*:: -Show full error trace. -*-O* _LEVEL_:: Optimization mode: 0 (default), 1, 2, 3. See *OPTIMIZATIONS* for details. -*--release*:: -Compile in release mode. Equivalent to *-O3 --single-module* -*-s*, *--stats*:: -Print statistics about the different compiler stages for the current build. Output time and used memory for each compiler -process. -*-p*, *--progress*:: -Print statistics about the progress for the current build. -*-t*, *--time*:: -Print statistics about the execution time. -*--no-color*:: -Disable colored output. - -=== tool -*tool* [tool] [switches] [programfile] [--] [arguments] - -Run a tool. The available tools are: context, dependencies, expand, flags, -format, hierarchy, implementations, types, and unreachable. - -Tools: - -*context*:: -Show context for given location. - -*dependencies*:: -Show tree of required source files. -+ -Options: -+ --- -*-D* _FLAG_, *--define*=_FLAG_:: - Define a compile-time flag. This is useful to con ditionally define types, methods, or commands based - on flags available at compile time. The default - flags are from the target triple given with *--tar* get-triple or the hosts default, if none is given. -*-f* _FORMAT_, *--format*=_FORMAT_:: - Output format 'tree' (default), 'flat', 'dot', or - 'mermaid'. -*-i* _PATH_, *--include*=_PATH_:: - Include path in output. -*-e* _PATH_, *--exclude*=_PATH_:: - Exclude path in output. -*--error-trace*:: - Show full error trace. -*--prelude*:: - Specify prelude to use. The default one initializes - the garbage collector. You can also use *--pre* lude=empty to use no preludes. This can be useful - for checking code generation for a specific source - code file. -*--verbose*:: - Show skipped and heads of filtered paths --- - -*expand*:: Show macro expansion for given location. - -*flags*:: Print all macro 'flag?' values - -*format*:: Format project, directories and/or files with the coding -style used in the standard library. You can use the -*--checkflag* to check whether the formatter would make any -changes. - -*hierarchy*:: -Show hierarchy of types from file. Also show class and struct -members, with type and size. Types can be filtered with a -regex by using the *-e* flag. +== Crystal Commands -*implementations*:: -Show implementations for a given call. Use *--cursor* to specify the cursor position. The format for the cursor position -is file:line:column. +=== Main commands + +*crystal-init(1)*:: Create a a new Crystal project + +*crystal-build(1)*:: Compile a Crystal program + +*crystal-docs(1)*:: Generate API docs for Crystal code -*types*:: Show type of main variables of file. - -*unreachable*:: -Show methods that are never called. The text output is a list -of lines with columns separated by tab. -+ -Output fields: -+ --- -*count*:: sum of all calls to this method (only with -*--tallies* option; otherwise skipped) -*location*:: pathname, line and column, all separated by colon -name -*lines*:: length of the def in lines -annotations --- -+ -Options: -+ --- -*-D* _FLAG_, *--define*=_FLAG_:: - Define a compile-time flag. This is useful to con ditionally define types, - methods, or commands based on flags available at compile time. The default - flags are from the target triple given with *--target-triple* or the hosts - default, if none is given. -*-f* _FORMAT_, *--format*=_FORMAT_:: - Output format 'text' (default), 'json', 'codecov', or 'csv'. -*--tallies*:: - Print reachable methods and their call counts as well. -*--check*:: Exit with error if there is any unreachable code. -*-i* _PATH_, *--include*=_PATH_:: - Include path in output. -*-e* _PATH_, *--exclude*=_PATH_:: - Exclude path in output (default: lib). -*--error-trace*:: - Show full error trace. -*--prelude*:: - Specify prelude to use. The default one initializes the garbage collector. You - can also use *--prelude=empty* to use no preludes. This can be useful for - checking code generation for a specific source code file. --- - -=== clear_cache +*crystal-env(1)*:: Print environment variables for the Crystal compiler + +*crystal-eval(1)*:: Evaluate a crystal program + +*crystal-play(1)*:: Run the Crystal playground + +*crystal-run(1)*:: Compile and run a Crystal program + +*crystal-spec(1)*:: Compile and run Crystal spec files + +*crystal-clear_cache*:: Clear the compiler cache (located at 'CRYSTAL_CACHE_DIR'). -=== help +*crystal-help*:: + Show help. Option *--help* or *-h* can also be added to each command for command-specific help. -=== version +*crystal-version*:: + Show version. +=== Tools + +*crystal-tool-context*:: Show context for given location + +*crystal-tool-dependencies(1)*:: Show tree of required source files + +*crystal-tool-expand*:: Show macro expansion for given location + +*crystal-tool-flags*:: Print all macro 'flag?' values + +*crystal-tool-format(1)*:: Format Crystal source files + +*crystal-tool-hierarchy*:: +Show hierarchy of types from file. Also show class and struct +members, with type and size. Types can be filtered with a +regex by using the *-e* flag. + +*crystal-tool-implementations*:: +Show implementations for a given call. Use *--cursor* to specify the cursor position. The format for the cursor position +is file:line:column. + +*crystal-tool-types*:: Show type of main variables of file. + +*crystal-tool-unreachable(1)*:: Identify methods that are never called + == Optimizations The optimization level specifies the codegen effort for producing optimal code. It's a trade-off between compilation performance (decreasing per optimization level) and