Debian Codegraph @

manual/binarygrammar.xml

raw
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE chapter SYSTEM "docbook-dtd-45/docbookx.dtd">
3
4 <chapter id="binarygrammar">
5 <title>Binary Grammars</title>
6
7 <section id="binaryvstextual">
8 <title>Security of Binary vs. Textual</title>
9 <para>
10 Textual grammars are the human readable plain-text input grammars as described in the rest of this manual.
11 Binary grammars are the compiled versions of textual grammars.
12 </para>
13 <para>
14 For the purpose of commercial distribution, textual grammars are terribly insecure;
15 anyone can take your carefully constructed grammar and use it as a basis of their own work.
16 Binary grammars are more secure in that it takes an active decompilation to get anything human
17 readable, and even then it will be undocumented and look rather different from the original grammar.
18 </para>
19 <para>
20 As of release 0.8.9.3142, VISL CG-3 can create and use binary grammars.
21 At this point they are basically memory dumps of the compiled grammars and can be trivially
22 decompiled by modifying the sources a bit. Future releases will have options to strenghten the security
23 of the binary grammars by excluding disused parts from the compilation.
24 </para>
25 </section>
26
27 <section id="binaryspeed">
28 <title>Loading Speed of Binary Grammars</title>
29 <para>
30 As of release 0.9.7.5729, the speed difference between binary and textual is down to factor 2 slower,
31 where previously it was factor 10. So there is no longer any pressing need to use binary grammars solely
32 for their speed advantage.
33 </para>
34 </section>
35
36 <section id="binaryhowto">
37 <title>How to...</title>
38 <para>
39 To compile a textual grammar to a binary form, use
40 <screen>
41 vislcg3 --grammar inputgrammar.txt --grammar-only --grammar-bin binarygrammar.cg3b
42 </screen>
43 (remember to set codepage if needed)
44 </para>
45 <para>
46 To later on use the binary grammar, simply do
47 <screen>
48 vislcg3 --grammar binarygrammar.cg3b
49 </screen>
50 </para>
51 <para>
52 VISL CG-3 will auto-detect binary grammars in that the first 4 bytes of the file are ['C','G','3','B'].
53 Binary grammars are neutral with regard to codepage and system endianness;
54 to maximize portability of grammars, strings are stored in UTF-8 and all integers are normalized.
55 </para>
56 </section>
57
58 <section id="binaryincompat">
59 <title>Incompatibilities</title>
60
61 <section id="binarygencg">
62 <title>vislcg / bincg / gencg</title>
63 <para>
64 Binary grammars generated with the older 'gencg' tool are not compatible with VISL CG-3 and
65 there are no plans to make them loadable. Nor are binary grammars generated with VISL CG-3 usable
66 with the older 'bincg'.
67 </para>
68 </section>
69
70 <section id="binarystatistics">
71 <title>--grammar-info, --grammar-out, --profile</title>
72 <para>
73 Since binary grammars cannot be written back out in textual form, the command line options
74 --grammar-info, --grammar-out, and --profile will not work in binary mode.
75 </para>
76 </section>
77 </section>
78 </chapter>