vlm | fa67ddc | 2004-06-03 03:38:44 +0000 | [diff] [blame] | 1 | WHAT TO READ? |
| 2 | ============= |
| 3 | |
vlm | e43659a | 2004-09-19 19:40:52 +0000 | [diff] [blame] | 4 | If you haven't installed the asn1c yet, read the INSTALL file for |
| 5 | a short installation guide. |
vlm | fa67ddc | 2004-06-03 03:38:44 +0000 | [diff] [blame] | 6 | |
vlm | d3686cd | 2004-09-06 08:08:32 +0000 | [diff] [blame] | 7 | For the list of asn1c command line options, see `asn1c -h` or `man asn1c`. |
| 8 | |
vlm | fa67ddc | 2004-06-03 03:38:44 +0000 | [diff] [blame] | 9 | For more complete documentation on this compiler and on using the |
vlm | 347bcfd | 2005-11-21 09:17:43 +0000 | [diff] [blame] | 10 | results of compilation phase, please look into asn1c-quick.pdf and |
| 11 | asn1c-usage.{pdf,html}. |
vlm | e43659a | 2004-09-19 19:40:52 +0000 | [diff] [blame] | 12 | If you are building the compiler from the sources, these documents reside |
| 13 | in the ./doc directory, otherwise they lie nearby the README file you're |
| 14 | reading right now. |
vlm | fa67ddc | 2004-06-03 03:38:44 +0000 | [diff] [blame] | 15 | |
vlm | d79b30d | 2004-09-05 10:41:23 +0000 | [diff] [blame] | 16 | Please also read the FAQ file. |
| 17 | |
vlm | fa67ddc | 2004-06-03 03:38:44 +0000 | [diff] [blame] | 18 | An excellent book on ASN.1 is written by Olivier Dubuisson: |
| 19 | "ASN.1 Communication between heterogeneous systems", ISBN:0-12-6333361-0. |
| 20 | |
vlm | 347bcfd | 2005-11-21 09:17:43 +0000 | [diff] [blame] | 21 | QUICK START (also check out asn1c-quick.pdf) |
| 22 | ============================================ |
vlm | fa67ddc | 2004-06-03 03:38:44 +0000 | [diff] [blame] | 23 | |
| 24 | After building [and installing] the compiler (see INSTALL), you may use |
| 25 | the asn1c command to compile the ASN.1 specification: |
| 26 | |
vlm | e43659a | 2004-09-19 19:40:52 +0000 | [diff] [blame] | 27 | asn1c <module.asn1> # Compile module |
vlm | fa67ddc | 2004-06-03 03:38:44 +0000 | [diff] [blame] | 28 | |
| 29 | If several specifications contain interdependencies, all of them must be |
| 30 | specified: |
| 31 | |
vlm | e43659a | 2004-09-19 19:40:52 +0000 | [diff] [blame] | 32 | asn1c <module1.asn1> <module2.asn1> ... # Compile interdependent modules |
vlm | fa67ddc | 2004-06-03 03:38:44 +0000 | [diff] [blame] | 33 | |
vlm | e43659a | 2004-09-19 19:40:52 +0000 | [diff] [blame] | 34 | If you are building the asn1c from the sources, the ./examples directory |
| 35 | contains several ASN.1 modules and a script to extract the ASN.1 modules |
| 36 | from RFC documents. Refer to the README file in that directory. |
| 37 | To compile the X.509 PKI module: |
vlm | fa67ddc | 2004-06-03 03:38:44 +0000 | [diff] [blame] | 38 | |
vlm | e43659a | 2004-09-19 19:40:52 +0000 | [diff] [blame] | 39 | ./asn1c/asn1c -P ./examples/rfc3280-*.asn1 # Compile-n-print |
vlm | fa67ddc | 2004-06-03 03:38:44 +0000 | [diff] [blame] | 40 | |
| 41 | In this example, -P option is used to instruct the compiler to print the |
| 42 | compiled text on the standard output instead of creating multiple .c |
vlm | d79b30d | 2004-09-05 10:41:23 +0000 | [diff] [blame] | 43 | and .h files for every ASN.1 type found inside the specified ASN.1 modules. |
| 44 | This is useful for debugging and test automation. |
vlm | fa67ddc | 2004-06-03 03:38:44 +0000 | [diff] [blame] | 45 | |
| 46 | The compiler -E and -EF options are used for testing the parser and |
| 47 | the semantic fixer, respectively. These options will instruct the compiler |
| 48 | to dump out the parsed (and fixed) ASN.1 specification as it was |
| 49 | "understood" by the compiler. It might be useful for checking |
| 50 | whether a particular syntactic construction is properly supported |
| 51 | by the compiler. |
| 52 | |
vlm | e43659a | 2004-09-19 19:40:52 +0000 | [diff] [blame] | 53 | asn1c -EF <module-to-test.asn1> # Check semantic validity |
vlm | fa67ddc | 2004-06-03 03:38:44 +0000 | [diff] [blame] | 54 | |
| 55 | |
| 56 | MODEL OF OPERATION |
| 57 | ================== |
| 58 | |
| 59 | The asn1c compiler works by processing the ASN.1 module specification |
| 60 | in several stages: |
| 61 | 1. In the first stage, the ASN.1 file is parsed. |
vlm | d79b30d | 2004-09-05 10:41:23 +0000 | [diff] [blame] | 62 | (Parsing produces an ASN.1 syntax tree for the subsequent levels) |
vlm | fa67ddc | 2004-06-03 03:38:44 +0000 | [diff] [blame] | 63 | 2. In the second stage, the syntax tree is "fixed". |
vlm | d79b30d | 2004-09-05 10:41:23 +0000 | [diff] [blame] | 64 | (Fixing is a process of checking the tree for semantic errors, |
| 65 | accompanied by the tree transformation into the canonical form) |
vlm | fa67ddc | 2004-06-03 03:38:44 +0000 | [diff] [blame] | 66 | 3. In the third stage, the syntax tree is compiled into the target language. |
| 67 | |
| 68 | There are several command-line options reserved for printing the results |
| 69 | after each stage of operation: |
| 70 | |
| 71 | <parser> => print (-E) |
| 72 | <parser> => <fixer> => print (-E -F) |
| 73 | <parser> => <fixer> => <compiler> => print (-P) |
| 74 | <parser> => <fixer> => <compiler> => save-compiled [default] |
| 75 | |
| 76 | |
| 77 | -- |
| 78 | Lev Walkin |
| 79 | vlm@lionet.info |