manpage: -fcorrect-logic, -ftrue-empty-strings, -ffalse-empty-strings

[xonotic/gmqcc.git] / doc / gmqcc.1

diff --git a/doc/gmqcc.1 b/doc/gmqcc.1
index 0bc0160e591c8581429f4a30f3b86f6c39ba60f4..defe7d01039f50a1852f889550fd9b772785b826 100644 (file)
--- a/doc/gmqcc.1
+++ b/doc/gmqcc.1
@@ -38,7 +38,7 @@ Default optimization level
 .IP 1
 Minimal optimization level
 .IP 0
-Disable optimization entierly
+Disable optimization entirely
 .RE
 .TP
 .BI "-O" name "\fR, " "" -Ono- name
@@ -50,17 +50,18 @@ be overwritten.
 List all possible optimizations and the optimization level they're
 activated at.
 .TP
-.BI "-std=" standard
-Use the specified standard for parsing QC code. The following standards
-are available:
-.IR gmqcc , qcc , fteqcc
-.TP
 .BI -W warning "\fR, " "" -Wno- warning
 Enable or disable a warning.
 .TP
 .B -Wall
 Enable all warnings. Overrides preceding -W parameters.
 .TP
+.BR -Werror ", " -Wno-error
+Controls whether or not all warnings should be treated as errors.
+.TP
+.BI -Werror- warning "\fR, " "" -Wno-error- warning
+Controls whether a specific warning should be an error.
+.TP
 .B -Whelp
 List all possible warn flags.
 .TP
@@ -74,11 +75,47 @@ List all possible compile flags.
 .B -nocolor
 Disables colored output
 .TP
+.BI -config= file
+Use an ini file to read all the -O, -W and -f flag from. See the
+CONFIG section about the file format.
+.TP
 .BI "-redirout=" file
 Redirects standard output to a \fIfile\fR
 .TP
-.BI "-rediterr=" file
+.BI "-redirerr=" file
 Redirects standard error to a \fIfile\fR
+.TP
+.BI "-std=" standard
+Use the specified standard for parsing QC code. The following standards
+are available:
+.IR gmqcc , qcc , fteqcc
+Selecting a standard also implies some -f options and behaves as if
+those options have been written right after the -std option, meaning
+if you changed them before the -std option, you're now overwriting
+them.
+.sp
+.BR -std=gmqcc " includes:"
+.in +4
+-fadjust-vector-fields
+.in
+.BR -std=qcc " includes:"
+.in +4
+.nf
+-fassign-function-types
+-f\fIno-\fRadjust-vector-fields
+.fi
+.in
+.BR -std=fteqcc " includes:"
+.in +4
+.nf
+-fftepp
+-ftranslatable-strings
+-fassign-function-types
+-Wternary-precedence
+-f\fIno-\fRadjust-vector-fields
+-f\fIno-\fRcorrect-ternary
+.fi
+.in
 .SH Warnings
 .TP
 .B -Wunused-variable
@@ -189,6 +226,10 @@ actually want. We recommend the \fI-fcorrect-ternary\fR option.
 .B -Wunknown-pragmas
 Warn when encountering an unrecognized \fI#pragma\fR line.
 .TP
+.B -Wunreachable-code
+Warn about unreachable code. That is: code after a return statement,
+or code after a call to a function marked as 'noreturn'.
+.TP
 .B -Wdebug
 Enable some warnings added in order to help debugging in the compiler.
 You won't need this.
@@ -256,3 +297,66 @@ soption.
 Normally vectors generate 4 defs, once for the vector, and once for
 its components with _x, _y, _z suffixes. This option
 prevents components from being listed.
+.TP
+.B -fcorrect-logic
+Most QC compilers translate if(a_vector) directly as an IF on the
+vector, which means only the x-component is checked. This causes all
+non-float types to use an appropriate NOT instruction on all logic
+operations and invert their use.
+.in +4
+.nf
+if (a_vector) // becomes
+if not(!a_vector)
+// likewise
+a = a_vector && a_float // becomes
+a = !!a_vector && a_float
+.fi
+.in
+.TP
+.B -ftrue-empty-strings
+An empty string is considered to be true everywhere. The NOT_S
+instruction usually considers an empty string to be false, this option
+effectively causes the unary not in strings to use NOT_F instead.
+.TP
+.B -ffalse-empty-strings
+An empty string is considered to be false everywhere. This means loops
+and if statements which depend on a string will perform a NOT_S
+instruction on the string before using it.
+.SH CONFIG
+The configuration file is similar to regular .ini files. Comments
+start with hashtags or semicolons, sections are written in square
+brackets and in each section there can be arbitrary many key-value
+pairs.
+.sp
+There are 3 sections currently:
+.IR flags ", " warnings ", and " optimizations .
+They contain a list of boolean values of the form `VARNAME = true` or
+`VARNAME = false`. The variable names are the same as for the
+corresponding -W, -f or -O flag written with only capital letters and
+dashes replaced by underscores.
+.sp
+Here's an example:
+.in +4
+.nf
+# a GMQCC configuration file
+[flags]
+    FTEPP = true
+    ADJUST_VECTOR_FIELDS = false
+    LNO = true
+
+[warnings]
+    UNUSED_VARIABLE = false
+    USED_UNINITIALIZED = true
+
+[optimizations]
+    PEEPHOLE = true
+    TAIL_RECURSION = true
+.fi
+.in
+.SH BUGS
+Please report bugs on <http://github.com/graphitemaster/gmqcc/issues>,
+or see <http://graphitemaster.github.com/gmqcc> on how to contact us.
+.SH SEE ALSO
+.IR qcvm (1)
+.SH AUTHOR
+See <http://graphitemaster.github.com/gmqcc>.