Update doc/specification.tex
[xonotic/gmqcc.git] / doc / qcvm.1
1 .\" qcvm mdoc manpage
2 .Dd January 31, 2013
3 .Dt QCVM 1 PRM
4 .Os
5 .Sh NAME
6 .Nm qcvm
7 .Nd A standalone QuakeC VM binary executor
8 .Sh SYNOPSIS
9 .Nm qcvm
10 .Op Cm options
11 .Op Cm parameters
12 .Ar program-file
13 .Sh DESCRIPTION
14 .Nm qcvm
15 is an executor for QuakeC VM binary files created using a QC
16 compiler such as gmqcc(1) or fteqcc. It provides a small set of
17 builtin functions, and by default executes the
18 .Fn main
19 function if there is one. Some options useful for debugging are
20 available as well.
21 .Sh OPTIONS
22 There are 2 types of options. Options for the executor, and parameter
23 options used to add parameters which are passed to the main function
24 on execution.
25 .Bl -tag -width Ds
26 .It Fl h , Fl -help
27 Show a usage message and exit.
28 .It Fl trace
29 Trace the execution. Each instruction will be printed to stdout before
30 executing it.
31 .It Fl profile
32 Perform some profiling. This is currently not really implemented, the
33 option is available nonetheless.
34 .It Fl info
35 Print information from the program's header instead of executing.
36 .It Fl disasm
37 Disassemble the program by function instead of executing.
38 .It Fl disasm-func Ar function
39 Search for and disassemble the given function.
40 .It Fl printdefs
41 List all entries from the program's defs-section. Effectively
42 listing all the global variables of the program.
43 This option disables execution.
44 .It Fl printfields
45 List all entries from the program's fields-section. Listing all
46 entity-fields declared in the program.
47 This option disables execution.
48 .It Fl printfuns
49 List functions and some information about their parameters.
50 This option disables execution. With a verbosity level of 1, builtin
51 numbers are printed. With a verbosity of 2, the function's sizes are
52 printed as well. This takes a little longer since the size is found by
53 searching for a
54 .Ql DONE
55 instruction in the code.
56 .It Fl v
57 Increase verbosity level, can be used multiple times.
58 .It Fl vector Ar 'x y z'
59 Append a vector parameter to be passed to
60 .Fn main Ns .
61 .It Fl float Ar number
62 Append a float parameter to be passed to
63 .Fn main Ns .
64 .It Fl string Ar 'text'
65 Append a string parameter to be passed to
66 .Fn main Ns .
67 .El
68 .Sh BUILTINS
69 The following builtin functions are available:
70 .Bl -ohang
71 .It Li 1) void print(string...) = #1;
72 .D1 Print the passed strings to stdout. At most 8 strings are allowed.
73 .It Li 2) string ftos(float) = #2;
74 .D1 Convert a float to a string.
75 .It Li 3) entity spawn() = #3;
76 .D1 Spawn an entity.
77 .It Li 4) void remove(entity) = #4;
78 .D1 Remove an entity.
79 .It Li 5) string vtos(vector) = #5;
80 .D1 Convert a vector to a string.
81 .It Li 6) void error(string...) = #6;
82 .D1 Print at most 8 strings to stdout and then exit with an error.
83 .It Li 7) float vlen(vector) = #7;
84 .D1 Get the length of a vector.
85 .It Li 8) string etos(entity) = #8;
86 .D1 Get the entity ID as string.
87 .It Li 9) float stof(string) = #9;
88 .D1 Convert a string to a float.
89 .It Li 10) string strcat(string, string) = #10;
90 .D1 Concatenate two strings, returning a tempstring.
91 .It Li 11) float strcmp(string, string) = #11;
92 .Li 12) float strncmp(string, string, float) = #11;
93 .D1 Compare two strings. Returns the same as the corresponding C functions.
94 .It Li 12) vector normalize(vector) = #12;
95 .D1 Normalize a vector so its length is 1.
96 .It Li 13) float sqrt(float) = #13;
97 .D1 Get a value's square root.
98 .El
99 .Sh SEE ALSO
100 .Xr gmqcc 1
101 .Sh AUTHOR
102 See <http://graphitemaster.github.com/gmqcc>.
103 .Sh BUGS
104 Please report bugs on <http://github.com/graphitemaster/gmqcc/issues>,
105 or see <http://graphitemaster.github.com/gmqcc> on how to contact us.