Lichen

Annotated docs/lplc.1

804:154d95f9de55
2017-04-04 Paul Boddie Added insert and reverse methods to the list implementation.
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).