.TH LPLC "1" "2017-02-09" "lplc 0.1" "User Commands"

.SH NAME

lplc \- Lichen Python-like compiler

.SH SYNOPSIS

.B lplc

.RI [ options ]

.I file

.br

.B lplc

.I --help

.br

.B lplc

.I --version

.SH DESCRIPTION

.B lplc

compiles programs written in the Lichen language, taking the indicated

.I file

representing the principal source file of a program, compiling the program to an

intermediate representation, and then building the result using a C compiler and

.B make

to produce an executable. Other source files need not be specified: they will be

identified by the compiler and loaded as required.

.SH OPTIONS

The following options may be specified:

.PP

.TP

.BR \-c ", " \-\-compile

Only partially compile the program; do not build or link it

.TP

.BR \-E ", " \-\-no\-env

Ignore environment variables affecting the module search path

.TP

.BR \-g ", " \-\-debug

Generate debugging information for the built executable

.TP

.BR \-G ", " \-\-gc\-sections

Remove superfluous sections of the built executable by applying the

.B \-\-gc\-sections

linker option and associated compiler options

.TP

.BR \-P ", " \-\-show\-path

Show the module search path

.TP

.BR \-q ", " \-\-quiet

Silence messages produced when building an executable

.TP

.BR \-r ", " \-\-reset

Reset (discard) cached information; inspect the whole program again

.TP

.BR \-R ", " \-\-reset\-all

Reset (discard) all program details including translated code

.TP

.BR \-t ", " \-\-no\-timing

Silence timing messages

.TP

.BR \-tb ", " \-\-traceback

Provide a traceback for any internal errors (development only)

.TP

.BR \-v ", " \-\-verbose

Report compiler activities in a verbose fashion (development only)

.PP

Some options may be followed by values, either immediately after the option

(without any space between) or in the arguments that follow them:

.PP

.TP

.B \-o

Indicate the output executable name

.TP

.B \-W

Show warnings on the topics indicated

.PP

Currently, the following warnings are supported:

.TP

.B all

Show all possible warnings

.TP

.B args

Show invocations where a callable may be involved that cannot accept

the arguments provided

.PP

Control over program organisation can be exercised using the following options

with each requiring an input filename providing a particular form of

information:

.TP

.B \-\-attr\-codes

Attribute codes identifying named object attributes

.TP

.B \-\-attr\-locations

Attribute locations in objects

.TP

.B \-\-param\-codes

Parameter codes identifying named parameters

.TP

.B \-\-param\-locations

Parameter locations in signatures

.PP

A filename can immediately follow such an option, separated from the option by

an equals sign, or it can appear as the next argument after the option

(separated by a space).

.PP

The following informational options can be specified to produce output instead

of compiling a program:

.PP

.TP

.BR \-h ", " \-? ", " \-\-help

Show a summary of the command syntax and options

.TP

.BR \-V ", " \-\-version

Show version information for this tool

.SH INCREMENTAL COMPILATION

Invocations of

.B lplc

without the reset options

.BR \-r ", " \-\-reset ", " \-R " or " \-\-reset\-all

will cause incremental translation and compilation to be attempted. Where

existing translated sources exist and where no changes to the object structures

or callable signatures are made, only updated sources will be generated and

compiled. Otherwise, where structures or signatures change in a way that is

incompatible with already-compiled code, the entire program will be generated

and compiled again.

.PP

The

.BR \-r " and " \-\-reset

options force inspection and compilation to occur again but will still attempt

to preserve structure and signature information. Meanwhile, the

.BR \-R " and " \-\-reset\-all

options remove all traces of previous program information, requiring that all

such information be generated again.

.SH PROGRAM CONFIGURATION

Use of the

.BR \-\-attr\-codes " and " \-\-param\-codes

options is intended to allow common catalogues of identifying codes to be

maintained. Similarly, use of the

.BR \-\-attr\-locations " and " \-\-param\-locations

options is intended to allow common representations to be maintained.

.PP

Beyond incremental compilation, these features would allow already-compiled

programs and libraries to exchange information in a compatible way, although

this is not yet supported in any significant way. However, the

.B \-\-attr\-locations

option can be useful in directing the attribute allocation process and

potentially making program representations more efficient.

.SH EXAMPLES

Compile the main program in

.BR hello.py ,

including all source files that the program requires:

.IP

lplc -o hello hello.py

.PP

This produces an output executable called

.B hello

in the current directory, assuming that

.B hello.py

can be compiled without errors.

.PP

To configure a program using existing attribute codes in

.B attrnames

and existing attribute positions in

.BR locations :

.IP

lplc -o hello hello.py --attr-codes=attrnames --attr-locations=locations

.PP

If attributes cannot be positioned in a way compatible with the given

.B locations

file, an error will be reported.

.SH FILES

.B lplc

produces an output executable file called

.B _main

unless the

.B \-o

option is given with a different name. Working data is stored in a directory

whose name is derived from the output executable name. Therefore, the working

data directory will be called

.B _main.lplc

unless otherwise specified. For example, an output executable called

.B hello

will have a working data directory called

.BR hello.lplc .

This is intended to allow work to proceed efficiently on multiple programs in

the same directory, although it can also create lots of unwanted directories.

.SH ENVIRONMENT

.TP

ARCH

Indicates a prefix to be used with tool names when building an executable. This

permits things like cross-compilation where tools have been provided with names

featuring architecture- and system-specific prefixes. For example,

.I mipsel-linux-gnu

may be used to indicate the use of tools for the MIPS architecture running

GNU/Linux in little-endian mode.

.TP

LICHENPATH

A collection of directories that are searched before those in the collection

comprising the default "module search path". This collection, if already defined

in the environment, may be excluded by specifying the

.BR \-E " (or " \-\-no\-env )

option.

.SH AUTHOR

Paul Boddie <paul@boddie.org.uk>

.SH RESOURCES

The project Web site: http://projects.boddie.org.uk/Lichen

.SH COPYRIGHT

Copyright \(co 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013,

2014, 2015, 2016, 2017 Paul Boddie <paul@boddie.org.uk>

.PP

This program is free software; you may redistribute it under the terms of

the GNU General Public License version 3 or (at your option) a later version.

This program has absolutely no warranty.

.SH SEE ALSO

.BR cc (1),

.BR make (1).