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