Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CRYSTAL(1)	 Crystal Compiler Command Line Reference Guide	    CRYSTAL(1)

NAME
     crystal --	Compiler for the Crystal language.

SYNOPSYS
     crystal command [switches]	programfile -- [arguments]

DESCRIPTION
     Crystal is	a statically type-checked programming language.	It was created
     with the beauty of	Ruby and the performance of C in mind.

USAGE
     You can compile and run a program by invoking the compiler	with a single
     filename:

     crystal some_program.cr

     Crystal files usually end with the	.cr extension, though this is not
     mandatory.

     Alternatively you can use the run command:

     crystal run some_program.cr

     To	create an executable use the build command:

     crystal build some_program.cr

     This will create an executable named "some_program".

     Note that by default the generated	executables are	not fully optimized.
     To	turn optimizations on, use the --release flag:

     crystal build --release some_program.cr

     Make sure to always use --release for production-ready executables	and
     when performing benchmarks.

     The optimizations are not turned on by default because the	compile	times
     are much 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 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 reposi-
	       tory, with a license file, a README file, a .travis.yml file
	       for Travis CI integration, 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 [options] [programfile] [--]	[arguments]

	       Compile program.

	       Options:

	       --cross-compile
			 Generate an object file for cross compilation and
			 prints	the command to build the executable.  The ob-
			 ject 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 map-
			 pings to the original source code for those tools.
	       --no-debug
			 Generate the output without any symbolic debug	sym-
			 bols.
	       --lto FLAG
			 Use ThinLTO --lto=thin.
	       -D FLAG,	--define FLAG
			 Define	a compile-time flag. This is useful to condi-
			 tionally 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 com-
			 piler to emit.	You can	use this to see	the generated
			 LLVM IR, LLVM bitcode,	assembly, and object files.
	       -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 use-
			 ful for passing environment specific information di-
			 rectly	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"	sec-
			 tion 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	tar-
			 get, such as whether SIMD operations are enabled or
			 not. The default set of attributes is set by the cur-
			 rent 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 --pre-
			 lude=empty to use no preludes.	This can be useful for
			 checking code generation for a	specific source	code
			 file.
	       --release
			 Turn on optimizations for the generated code, which
			 are disabled by default.
	       --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.
	       --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-com-
			 pilation. 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 mark-
	       down. The output	is saved in html format	on the created docs/
	       folder. More information	about documentation conventions	can be
	       found at	https://crystal-lang.org/docs/conventions/document-
	       ing_code.html.

	       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 ex-
			 tracted 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 dis-
			 covering 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	pat-
			 tern 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	gener-
			 ated when this	option is set.
	       --sitemap-priority PRIO
			 Set the priority assigned to sitemap entries (de-
			 fault:	1.0).
	       --sitemap-changefreq FREQ
			 Set the changefreq assigned to	sitemap	entries	(de-
			 fault:	never).

     env [variables]

	       Print Crystal-specific environment variables in a format	com-
	       patible 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_PATH
			 Please	see ENVIRONMENT	VARIABLES.

	       CRYSTAL_VERSION
			 Contains Crystal version.

     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 map-
			 pings to the original source code for those tools.
	       --no-debug
			 Generate the output without any symbolic debug	sym-
			 bols.
	       -D FLAG,	--define FLAG
			 Define	a compile-time flag. This is useful to condi-
			 tionally 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.
	       --release
			 Turn on optimizations for the generated code, which
			 are disabled by default.
	       -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 [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 [options] [programfile] [--] [arguments]

	       The default command. Compile and	run program.

	       Options:	Same as	the build options.

     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 map-
			 pings to the original source code for those tools.
	       --no-debug
			 Generate the output without any symbolic debug	sym-
			 bols.
	       -D FLAG,	--define FLAG
			 Define	a compile-time flag. This is useful to condi-
			 tionally 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.
	       --release
			 Turn on optimizations for the generated code, which
			 are disabled by default.
	       -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] [switches] [programfile] [--] [arguments]

	       Run a tool. The available tools are: context, format, hierar-
	       chy, implementations, and types.

	       Tools:

		     context
			     Show context for given location.

		     expand  Show macro	expansion for given location.

		     format  Format project, directories and/or	files with the
			     coding style used in the standard library.	You
			     can use the --check flag 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.

		     implementations
			     Show implementations for a	given call. Use
			     --cursor to specify the cursor position. The for-
			     mat for the cursor	position is file:line:column.

		     types   Show type of main variables of file.

     help, --help, -h

	       Show help. Option --help	or -h can also be added	to each	com-
	       mand for	command-specific help.

     version, --version, -v

	       Show version.

ENVIRONMENT VARIABLES

     CRYSTAL_CACHE_DIR
	       Defines path where Crystal caches partial compilation results
	       for faster subsequent builds. This path is also used to tempo-
	       rarily store executables	when Crystal programs are run with
	       'crystal	run' rather than 'crystal build'.

     CRYSTAL_PATH
	       Defines paths where Crystal searches for	required files.

     CRYSTAL_OPTS
	       Defines options for the Crystal compiler	to be used besides the
	       command line arguments. The syntax is identical to the command
	       line arguments. This is hany when using Crystal in build	set-
	       ups, for	example	'CRYSTAL_OPTS=--debug make build'.

SEE ALSO
     shards(1)
     https://crystal-lang.org/			   The official	web site.
     https://github.com/crystal-lang/crystal	   Official Repository.

UNIX				     Epoch				  UNIX

NAME | SYNOPSYS | DESCRIPTION | USAGE | OPTIONS | ENVIRONMENT VARIABLES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=crystal&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help