--- name: "cyc" section: "1" platform: "linux" package: "zinc-compiler" version: "1.0.2-2" release: "Debian 3.1 (Sarge)" platforms: ["linux"] url: "https://new.carta.tech/cyc" --- # cyc(1) A native code compiler for Zinc. ## NAME **cyc** – A native code compiler for Zinc. ## SYNOPSIS **cyc** \[*option* ...\] *file* ... ## DESCRIPTION **cyc** is a native code compiler for the multi-paradigm declarative language Zinc, which is an extended version of Curry featuring type classes. Normally, it performs compilation, assembly, and linking. The \`\`overall options'' allow stopping this process at an intermediate stage. For example, the **-c** option says not to run the linker. The output then consists of object files output by the assembler. Other options control one stage of processing; for instance, the **--debug** option tells **cyc** to compile Zinc modules such that they can be evaluated by the declarative debugger. The **cyc** program accepts options and file names as operands. Options and file names can be mixed on the command line. In general, the order of options is not relevant with the exception of additional libraries specified with **-l** options. On many systems, these should be specified last on the command line in order to ensure proper linking of programs. The source language of a file and the associated processing is determined by the file name extension. Argument names which end with *.curry* are taken to be Zinc source, names ending in *.lcurry* are taken to be literate Zinc source, names ending in *.c* are taken to be C code, names ending in *.s* are taken to be assembler programs, and *.o* are object files. By default, a program linked with **cyc** executes the goal main.main. It is possible to specify a different goal with the **-e** option. If the type of the goal is **IO** *t*, for some arbitrary type *t*, the program executes the corresponding I/O action. Otherwise, the goal is evaluated and its solutions are presented incrementally on the standard output. ### Overall Options The following options control the general processing of source files. - **-n** Do not execute any command, but display each command that normally would be executed. - **-v** Display each command before it is executed by **cyc**. - **-C** Stop processing after generating C code from the Zinc source modules. - **-S** Stop processing after generating assembler code from the Zinc and C source files. - **-c** Compile and assemble the source file but do not link. - **-o** *file* Place the output in a file named *file*. Since only one output file can be specified, it does not make sense to use **-o** when compiling more than one input file unless you are producing an executable file as output. If **-o** is not specified, the default is to put an executable file in *a.out*, the object file for *source**.suffix* in *source**.o* its assembler file in *source**.s*, and its C file in *source**.c*. ### Compiling Zinc Modules The names of Zinc source files must end with *.curry* or *.lcurry*. The latter are taken to contain literate Zinc source and are deliterated first. All Zinc source files are compiled into C code. In addition, for every source file *file**.curry* and *file**.lcurry*, respectively, the compiler creates a file *file**.icurry* containing the module's interface. The compiler uses module interfaces when processing import declarations in a source module. In order for the compiler to find the interfaces of imported modules, the name of the source file should agree with its module name. Hierarchical module names of the form A.B.C are mapped onto the filesystem as in Java, i.e., the compiler expects to find the interface of this module in file *C.icurry* in directory *A/B* relative to the directory where the compiler was invoked or to one of the directories specifying the import search path. The following options control the compilation of Zinc source into C code. - **-g** Prepare the compiled code for executing the program with the declarative debugger. Note that code compiled with this option is incompatible with code compiled without this option. This option must therefore be used consistently for compiling and linking all modules of a program. - **--debug** Synonym for **-g**. - **--trusted** This flag has an effect only in conjunction with one of previous options. It tells that debugger that it can trust all functions from a module compiled with this flag. The debugger will not ask questions about such functions. - **-i** *dir* Add directory *dir* to the list of paths used to locate interface files. By default, the compiler searches for interface files in the current directory and in its standard library directory *${exec\_prefix}/lib/curry*. - **-H** *size* Change the heap size used by the compiler to *size*. It is possible to use the abbreviations *size*k and *size*M to specify the heap size in kBytes and MBytes, respectively. Note that this option does not effect the heap size of the compiled executable. Use **-h** *size* for this (see below). ### Compiling C Files The following list describes only the most common options understood by **cyc** when compiling C source either directly or as a result of previously compiling Zinc source into C code. In fact, **cyc** passes on most of its options to the C compiler. For a detailed description of these options see the [gcc(1)](/gcc/1.md) man page. - **-D** *name* Predefine *name* as a macro, with definition 1. - **-D** *name=defn* Predefine *name* as a macro with definition *defn*. - **-U** *name* Cancel any previous definition of *name*, either built in or provided with a **-D** definition. - **-I** *dir* Add directory *dir* to the list of paths used to locate header files. The standard library directory (*${exec\_prefix}/lib/curry*) is always included in this list. - **-O** equivalent to **-O1**. - **-O***level* Controls optimization of the compiled code. **-O0** disables all optimizations. Note that **-O3** and higher levels will fail to produce valid code for Zinc modules on many architectures. - **--ccopt** *opt* Passes the option *opt* to the C compiler without interpretation. For instance, in order to include debugging symbols in the compiled C code, invoke the compiler with **--ccopt** **-g**. ### Linking The following options are relevant while linking a program. The compiler creates a tiny C code file in this phase, which contains the startup code initializing the Zinc runtime system and starting the evaluation of the goal. This file is compiled like other C code during the link phase. - **-g** Compile a program that invokes the declarative debugger. All Zinc modules must have been compiled with the **-g** option as well. - **--debug** Synonym for **-g**. - **-h** *size* Use *size* bytes for the heap of the Zinc program. Note that actually twice as much memory is allocated for the heap because the runtime system uses a two-space copying collector. The abbreviations *size*k and *size*M can be used for specifying the size in kBytes and MBytes, respectively. The default is to use a 4 MByte heap. - **-k** *size* Use *size* bytes for the stack of the Zinc program. The abbreviations *size*k and *size*M can be used for specifying the size in kBytes and MBytes, respectively. The default is to use a 512 kByte stack. - **-t** *size* Use *size* bytes for the trail stack of the Zinc program. The abbreviations *size*k and *size*M can be used for specifying the size in kBytes and MBytes, respectively. The default is to use a 512 kByte trail stack. - **-p** Print cumulated execution times and memory usage statistics at the end of the run. If specified more than once, also print memory statistics at each garbage collection. - **-e** *goal* Evaluate *goal* instead of main.main. The *goal* is evaluated with respect to the Zinc module that occurs last on the command line, the module specified with the **-M** option, or the Zinc prelude otherwise. - **-T** *goal* Compute the type of *goal*. The *goal*'s type is computed with respect to the Zinc module that occurs last on the command line, the module specified with the **-M** option, or the Zinc prelude otherwise. - **-M** *module* An explicit goal specified with the **-e** option is evaluated with respect to the module *module* if no other Zinc module occurs on the command line. *module* is either the name of the source file (ending in *.lcurry* or *.curry*) or the name of a module whose source can be located in the current directory. - **-L** *dir* Add directory *dir* to the list of paths used to locate libraries specified with **-l** options. The standard library directory *${exec\_prefix}/lib/curry* is always included in this list. - **-l** *lib* Search the library named *lib* when linking. - **--ldopt** *opt* Passes the option *opt* to the C compiler without interpretation. In contrast to **--ccopt** (see above), *opt* is used only during the link phase. ### Running Programs The operation of a Zinc program depends on the type of the goal being evaluated. If it is of type IO *t*, the I/O action described by the goal is executed. All command line arguments except for the runtime system options (see below) are available to the program and can be accessed with the function System.getArgs. If the goal's type is not IO *t*, the program computes and prints the solutions of the goal with a depth first search strategy. A solution comprises the normal form of the goal and the bindings and constraints for its free variables. When run on an interactive terminal, solutions are presented one by one giving the user a chance to stop the computation after each solution. Otherwise, all solutions of the goal are computed. This behavior can be changed by passing one of the options **-i** and **-n** to the program. If invoked with **-i**, the program computes the solutions incrementally as if it were run on an interactive terminal. If invoked with **-n**, the goal's solutions are computed all at once. All Zinc programs run with fixed size heap, stack, and trail. Their sizes can be specified at link time, but can be changed at run-time by passing options to the Zinc runtime system. Such options must be enclosed with **+RTS** and **-RTS** arguments on the command line. The **-RTS** switch may be omitted if it is the last argument on the command line. The Zinc runtime system understands the following options: - **-b***mode* Use buffer mode *mode* for the standard input and output of the program where the following *mode*s are recognized - **n** Unbuffered - **l** Line buffered - **f** *n* Fully buffered The optional number *n* allows specifying the buffer size when using fully buffered mode. - **-h** *n* Use *n* bytes for the heap in this run of the program. Note that actually twice as much memory is allocated for the heap because the runtime system uses a two-space copying collector. The abbreviations *n*k and *n*M can be used for specifying the size in kBytes and MBytes, respectively. - **-k** *n* Use *n* bytes for the stack in this run of the program. The abbreviations *n*k and *n*M can be used for specifying the size in kBytes and MBytes, respectively. - **-t** *n* Use *n* bytes for the trail stack in this run of the program. The abbreviations *n*k and *n*M can be used for specifying the size in kBytes and MBytes, respectively. - **-p** Print cumulated execution times and memory usage statistics at the end of the run. If specified more than once, also print memory statistics at each garbage collection. - **-d** Turn on the low-level tracer of the abstract machine. In general you do not want to see its output, but it may give hints to why a program does not compute an expected solution or runs into a deadlock. Beware that tracing can slow down program execution considerably and the output may be excessively large. ## ENVIRONMENT - CURRY\_PATH The environment variable CURRY\_PATH is used to locate the compiler executables. The default value is *${exec\_prefix}/lib/curry*. - CURRY\_IMPORTS The environment variable CURRY\_IMPORTS contains a colon-separated list of directories that are searched for imported interfaces, included header files, and library files. The default value is $CURRY\_PATH. ## FILES - *${exec\_prefix}/lib/curry/cycc* The Zinc to C compiler. - *${exec\_prefix}/lib/curry/\*.icurry*, *${exec\_prefix}/lib/curry/\*.h* Interface and header files for the standard library and runtime system of the Zinc compiler. - *${exec\_prefix}/lib/curry/libcurry.a* The runtime system and standard library. - *${exec\_prefix}/lib/curry/libcurry\_g.a* Standard library prepared for debugging. All library modules have been compiled with **--trusted**. ## EXAMPLES - cyc test.curry This command compiles and links the Zinc module in *test.curry*. The file *test.curry* must define the module main. The executable is put in *a.out* and evaluates the goal main.main. - cyc -h12M -O2 A.lcurry B.lcurry -o B This command compiles and links the Zinc modules in *A.lcurry* and *B.lcurry* in that order. Both files are taken to contain literate Zinc source. The code is optimized by the C compiler using optimization level 2. The executable is put in file *B*. It evaluates the goal main.main and uses a larger default heap (12 MBytes). File *B.lcurry* should define the main. - cyc -c nat.curry - cyc -e add n Z =:= S Z where n free nat.o -Mnat -o one The first of these commands compiles the Zinc module in *nat.curry* and places the object file in *nat.o*. The second command then links the object file into a program which evaluates the goal add n Z =:= S Z where n free in the context of this module. Note that this context must be specified explicitly with a **-M** option because no Zinc module was named on the second command line. The executable is placed in *one*. - cyc -e length Xs where Xs free This command compiles and links a program that evaluates the goal length Xs where Xs free. The executable is placed in *a.out*. - a.out -x +RTS -k512k -h8M -t0 -RTS foo executes *a.out* with an 8 MByte heap, a 512 kByte stack, and no trail stack. The arguments **-x** and **foo** are passed to the Zinc program and are available from Zinc code via System.getArgs. Note that running a program without a trail stack, as in this example, requires that the code is completely deterministic and does not use encapsulated search. ## SEE ALSO [cyi(1)](/cyi/1.md), [cymake(1)](/cymake/1.md), [gcc(1)](/gcc/1.md) ## AUTHOR This man page was written by Wolfgang Lux for the Muenster Curry Compiler, and latter adapted by Diego Berrueta to the Zinc Project.