From fd7446ce00a105a593cf748dec711461ffcbfef1 Mon Sep 17 00:00:00 2001 From: Sei Lisa Date: Thu, 18 Jan 2018 16:41:40 +0100 Subject: [PATCH] Update with the latest additions. Most notably, include #line information. --- index.html | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/index.html b/index.html index 88c9e86..34d5721 100644 --- a/index.html +++ b/index.html @@ -208,9 +208,11 @@ h1 { background: #2080C0; color: white; padding:25px 5% 8px; margin: 4% 7% 0px;

#pragma and #line

-

The optimizer option ProcessPre enables processing of certain preprocessor directives that control compilation. Only #pragma and #line are supported for now. Typically these directives pass through the preprocessor unchanged (not always; see note below about gcc and #line), so they will reach the optimizer if a preprocessor is used. The rest of preprocessor directives will be ignored.

+

The optimizer option ProcessPre enables processing of certain preprocessor directives that control compilation. Only #pragma and #line are supported for now. Typically these directives pass through the preprocessor unchanged (not always; see note below about GNU cpp and #line), so they will reach the optimizer when a preprocessor is used. The rest of preprocessor directives will be ignored.

-

#pragma is a special C preprocessor directive that allows compilers to extend the language with certain options. In the case of this optimizer, the #pragma directive is used to enable/disable on the fly the parsing options and extensions. Even ProcessPre itself can be disabled (it can't be enabled this way because when disabled, #pragma directives aren't processed).

+

The #line directive is not supposed to be used by the programmer. C/C++ preprocessors, including Boost::Wave, mcpp and GNU cpp, automatically generate them whenever the lines in the original file lose synchronization with the preprocessor's output, in order to keep track of which original line produced a certain output line, for error reporting and debugging purposes. As of version 0.2.2beta, this directive does indeed track which input line generated a certain output line, generating errors with a line number that refers to the original file rather than the preprocessed/optimized file, and including the name of the file where the error was found when it differs from the initial source.

+ +

#pragma is a special C preprocessor directive that allows compilers to extend the language with certain options. In the case of this optimizer, the #pragma directive is used to enable/disable on the fly the parsing options and extensions, taking precedence over all others. Even ProcessPre itself can be disabled (it can't be enabled this way because when disabled, #pragma directives aren't processed).

To use this feature, type the command like this:

@@ -251,8 +253,6 @@ h1 { background: #2080C0; color: white; padding:25px 5% 8px; margin: 4% 7% 0px;

For a description of each, you can invoke the program from the command line with: python main.py -O help (that's the upper case letter O, not the number zero). Note, however, that the only options that can be used in #pragma directives inlined in the code are the options listed above, which are the ones that affect the parsing, not the optimization.

-

The #line directive is not supposed to be used by the programmer. Preprocessors including Boost::Wave, mcpp and GNU cpp automatically generate them whenever the lines in the original file lose synchronization with the preprocessor's output, in order to keep track of which original line produced a certain output line, for error reporting and debugging purposes. As of version 0.2.1beta, this directive doesn't do anything, but there are plans to use it for the same purpose: to track which input line generated a certain output line, in order to generate errors where the line numbers refer to the original file rather than the preprocessed/optimized file.

-

Important: Changing options in the middle of the program may not be well supported. In particular, activating and deactivating in the same program certain options like BreakCont may crash the optimizer. Changing the options at the beginning of the script should be safe.

Note: GNU cpp actually generates a preprocessor command that only contains the line number and the file name, pretty much like a #line directive does, but without the line part. The parser deals with that format correctly, treating it as if it was a #line directive.

@@ -429,7 +429,7 @@ but this will cause an error:

String constant folding

-

This optimization is turned off by default, as it can be counter-productive. It enables concatenating constants together. However, consider this situation:

+

This optimization is turned off by default, as it can be counter-productive. It enables concatenating string constants together. However, consider this situation:

string a = "A very long string that appears in this script once" + ", or not";
 string b = "A very long string that appears in this script once" + " or twice";
@@ -443,7 +443,7 @@ but this will cause an error:
 
 
This program is designed to work as a filter. It can read from standard input if the file name argument is "-", and it can (and does by default) output the result to standard output. Any errors and warnings go to standard error always, to not interfere with the script being output.

 
-
Running it by hand to optimize your scripts can be cumbersome. The intention is for it to act as a filter that is transparent to the user; however, as of this writing there's no support for any viewer or IDE, as it is still a young project. Run it without parameters to see the invocation help, for example with python main.py. Redirect the output to a file if you want to store the result, possibly to open it with an editor and copy it to the clipboard. Or under X Window, if you install the package xclip, you can pipe the output directly to xclip -quiet -selection clipboard to copy it to the clipboard, rather than using a file, so you can paste it directly into the viewer. Examples:

+
Running it by hand to optimize your scripts can be cumbersome. The intention is for it to act as a filter that is transparent to the user; however, as of this writing there's no support for any viewer or IDE, as it is still a young project. Run it without parameters to see the invocation help, for example with python main.py. Redirect the output to a file if you want to store the result, possibly to open it with an editor and copy it to the clipboard. Or under X Window, if you install the package xclip, you can pipe the output directly to xclip -quiet -selection clipboard to copy it to the clipboard, rather than using a file, so you can paste it into the viewer. Examples:

 
 
python main.py myscript.lsl | xclip -quiet -selection clipboard
 

@@ -475,8 +475,6 @@ but this will cause an error:
 
 
Making the optimizer smarter is one primary objective. Conversion to SSA form is currently not performed, and would be nice to have, for one, to enable more optimizations where values are not used. There are a number of TODO items in the code about optimizations pending to implement.

 
-
Another goal is to add the possibility to link each output line with its source counterpart, so that in case of a server side compilation error, the source line corresponding to the actual line where the error happened can be displayed. Currently, server-side compilation errors should be rare (unless there are bugs in the optimizer) as there will be few situations in which they won't be caught by the optimizer's parser first. This would also allow warnings output by the optimizer (e.g. an expression in globals not resolving to a constant) to be related to a source line. Currently those warnings don't tell where the error occurred.

-
 
Lastly, implementation of some kind of machine-readable way to inform the invoker about the available options, is also in the plans. That would allow the plugin or viewer or whatever to present a dialog with the options for invoking the optimizer.