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).
