Lichen

docs/lplc.1

932:c07b0dd14f85
13 months ago Paul Boddie Moved integer instantiation support to library functions.
     1 .TH LPLC "1" "2017-02-09" "lplc 0.1" "User Commands"     2 .SH NAME     3 lplc \- Lichen Python-like compiler     4 .SH SYNOPSIS     5 .B lplc     6 .RI [ options ]     7 .I file     8 .br     9 .B lplc    10 .I --help    11 .br    12 .B lplc    13 .I --version    14 .SH DESCRIPTION    15 .B lplc    16 compiles programs written in the Lichen language, taking the indicated    17 .I file    18 representing the principal source file of a program, compiling the program to an    19 intermediate representation, and then building the result using a C compiler and    20 .B make    21 to produce an executable. Other source files need not be specified: they will be    22 identified by the compiler and loaded as required.    23 .SH OPTIONS    24 The following options may be specified:    25 .PP    26 .TP    27 .BR \-c ", " \-\-compile    28 Only partially compile the program; do not build or link it    29 .TP    30 .BR \-E ", " \-\-no\-env    31 Ignore environment variables affecting the module search path    32 .TP    33 .BR \-g ", " \-\-debug    34 Generate debugging information for the built executable    35 .TP    36 .BR \-G ", " \-\-gc\-sections    37 Remove superfluous sections of the built executable by applying the    38 .B \-\-gc\-sections    39 linker option and associated compiler options    40 .TP    41 .BR \-P ", " \-\-show\-path    42 Show the module search path    43 .TP    44 .BR \-q ", " \-\-quiet    45 Silence messages produced when building an executable    46 .TP    47 .BR \-r ", " \-\-reset    48 Reset (discard) cached information; inspect the whole program again    49 .TP    50 .BR \-R ", " \-\-reset\-all    51 Reset (discard) all program details including translated code    52 .TP    53 .BR \-t ", " \-\-no\-timing    54 Silence timing messages    55 .TP    56 .BR \-tb ", " \-\-traceback    57 Provide a traceback for any internal errors (development only)    58 .TP    59 .BR \-v ", " \-\-verbose    60 Report compiler activities in a verbose fashion (development only)    61 .PP    62 Some options may be followed by values, either immediately after the option    63 (without any space between) or in the arguments that follow them:    64 .PP    65 .TP    66 .B \-o    67 Indicate the output executable name    68 .TP    69 .B \-W    70 Show warnings on the topics indicated    71 .PP    72 Currently, the following warnings are supported:    73 .TP    74 .B all    75 Show all possible warnings    76 .TP    77 .B args    78 Show invocations where a callable may be involved that cannot accept    79 the arguments provided    80 .PP    81 Control over program organisation can be exercised using the following options    82 with each requiring an input filename providing a particular form of    83 information:    84 .TP    85 .B \-\-attr\-codes    86 Attribute codes identifying named object attributes    87 .TP    88 .B \-\-attr\-locations    89 Attribute locations in objects    90 .TP    91 .B \-\-param\-codes    92 Parameter codes identifying named parameters    93 .TP    94 .B \-\-param\-locations    95 Parameter locations in signatures    96 .PP    97 A filename can immediately follow such an option, separated from the option by    98 an equals sign, or it can appear as the next argument after the option    99 (separated by a space).   100 .PP   101 The following informational options can be specified to produce output instead   102 of compiling a program:   103 .PP   104 .TP   105 .BR \-h ", " \-? ", " \-\-help   106 Show a summary of the command syntax and options   107 .TP   108 .BR \-V ", " \-\-version   109 Show version information for this tool   110 .SH INCREMENTAL COMPILATION   111 Invocations of   112 .B lplc   113 without the reset options   114 .BR \-r ", " \-\-reset ", " \-R " or " \-\-reset\-all   115 will cause incremental translation and compilation to be attempted. Where   116 existing translated sources exist and where no changes to the object structures   117 or callable signatures are made, only updated sources will be generated and   118 compiled. Otherwise, where structures or signatures change in a way that is   119 incompatible with already-compiled code, the entire program will be generated   120 and compiled again.   121 .PP   122 The   123 .BR \-r " and " \-\-reset   124 options force inspection and compilation to occur again but will still attempt   125 to preserve structure and signature information. Meanwhile, the   126 .BR \-R " and " \-\-reset\-all   127 options remove all traces of previous program information, requiring that all   128 such information be generated again.   129 .SH PROGRAM CONFIGURATION   130 Use of the   131 .BR \-\-attr\-codes " and " \-\-param\-codes   132 options is intended to allow common catalogues of identifying codes to be   133 maintained. Similarly, use of the   134 .BR \-\-attr\-locations " and " \-\-param\-locations   135 options is intended to allow common representations to be maintained.   136 .PP   137 Beyond incremental compilation, these features would allow already-compiled   138 programs and libraries to exchange information in a compatible way, although   139 this is not yet supported in any significant way. However, the   140 .B \-\-attr\-locations   141 option can be useful in directing the attribute allocation process and   142 potentially making program representations more efficient.   143 .SH EXAMPLES   144 Compile the main program in   145 .BR hello.py ,   146 including all source files that the program requires:   147 .IP   148 lplc -o hello hello.py   149 .PP   150 This produces an output executable called   151 .B hello   152 in the current directory, assuming that   153 .B hello.py   154 can be compiled without errors.   155 .PP   156 To configure a program using existing attribute codes in   157 .B attrnames   158 and existing attribute positions in   159 .BR locations :   160 .IP   161 lplc -o hello hello.py --attr-codes=attrnames --attr-locations=locations   162 .PP   163 If attributes cannot be positioned in a way compatible with the given   164 .B locations   165 file, an error will be reported.   166 .SH FILES   167 .B lplc   168 produces an output executable file called   169 .B _main   170 unless the   171 .B \-o   172 option is given with a different name. Working data is stored in a directory   173 whose name is derived from the output executable name. Therefore, the working   174 data directory will be called   175 .B _main.lplc   176 unless otherwise specified. For example, an output executable called   177 .B hello   178 will have a working data directory called   179 .BR hello.lplc .   180 This is intended to allow work to proceed efficiently on multiple programs in   181 the same directory, although it can also create lots of unwanted directories.   182 .SH ENVIRONMENT   183 .TP   184 ARCH   185 Indicates a prefix to be used with tool names when building an executable. This   186 permits things like cross-compilation where tools have been provided with names   187 featuring architecture- and system-specific prefixes. For example,   188 .I mipsel-linux-gnu   189 may be used to indicate the use of tools for the MIPS architecture running   190 GNU/Linux in little-endian mode.   191 .TP   192 LICHENPATH   193 A collection of directories that are searched before those in the collection   194 comprising the default "module search path". This collection, if already defined   195 in the environment, may be excluded by specifying the   196 .BR \-E " (or " \-\-no\-env )   197 option.   198 .SH AUTHOR   199 Paul Boddie <paul@boddie.org.uk>   200 .SH RESOURCES   201 The project Web site: http://projects.boddie.org.uk/Lichen   202 .SH COPYRIGHT   203 Copyright \(co 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013,   204 2014, 2015, 2016, 2017 Paul Boddie <paul@boddie.org.uk>   205 .PP   206 This program is free software; you may redistribute it under the terms of   207 the GNU General Public License version 3 or (at your option) a later version.   208 This program has absolutely no warranty.   209 .SH SEE ALSO   210 .BR cc (1),   211 .BR make (1).