Using the Compilation Tool

Getting Help

Run the following command to obtain help information:

./asn1rs-cli --help 

The following information is displayed:

ASN.1 Rust Compiler 1.2.0

USAGE:
    asn1rs-cli [FLAGS] [OPTIONS] --input <ASN.1 file (list)> --method <Transmission syntax (aper|uper|eper|ber...)> [SUBCOMMAND]

FLAGS:
    -C, --comments        Extracts log information to an abstract syntax file
    -D, --debug           Prints debugging information to a file
    -h, --help            Prints help information
    -r, --intermediate    Exports intermediate results to a file
    -V, --version         Prints version information

OPTIONS:
        --dump-types <CSV file path>
            The console dumps the compiled type list to a CSV file.

    -i, --input <ASN.1 file (list)>
            Select one or more ASN.1 text files, for example, -i s1.asn x2.asn. You can also use wildcard characters, for example, -i *.asn.

        --merge <Directory name. A multi-level directory can be specified, for example, a/b/c. The merging result is output to exports/a/b/c.>
            Merge compilation. If ASN.1 files are not merged, each ASN.1 file is compiled and output independently. If this option is used, all input ASN.1 files are merged to generate a target file.

    -m, --method <Transmission syntax (aper|uper|eper|ber...)>
            Select a rule for encoding and decoding. The selected rule applies to all input files in the current CLI.


SUBCOMMANDS:
    cc       [core] Compiles ASN.1 files into C code
    cceos    [extension] C backend LTE EOS version
    ccnr     [core] Compiles ASN.1 files into CPP code
    diff     [extension] Checks whether the version change of the ASN.1 file meets the requirements
    help     Prints this message or the help of the given subcommand(s)
    xmlc     [core] Compiles ASN.1 files into XML files

Sub-parameters

The tool has many sub-parameters. For example, you can run the following command to view the help information about the cc sub-parameter:

./asn1rs-cli cc --help

The following information is displayed:

asn1rs-cli-cc 
[Core] Compiles ASN.1 files into C code

USAGE:
    asn1rs-cli --input <ASN.1 file (list)> --method <Transmission syntax (aper|uper|eper|ber...)> cc [FLAGS] [OPTIONS]

FLAGS:
        --count-like-present    When the SEQUENCE OF type is an optional member, uses its count field as the present identifier in the interface
    -h, --help                  Prints help information
        --testcases             Generates the C file and header file of the testcase based on the defined values. This flag depends on --values
        --values                Generates the definition of all values. This flag depends on --mode full
    -V, --version               Prints version information

OPTIONS:
    -C, --cinline <List of types for which inline C code needs to be generated. Use commas (,) to separate the types. Generating inline C code for all types is not supported. This is to avoid massive amount of code.>
            The specified types are directly expanded to C code that contains encoding and decoding logic. During code generation, the compiler program optimizes the encoding and decoding performance of types specified by this option.

        --enum-as-uint <Data type (u8|u16|u32)>
            Set the C interface of the ENUMERATED type to u8, u16, or u32. Do not use the enum type of C.

    -e, --extension <Extension (rust)>
            rust: Header file used to generate Native-Rust

        --limits <Specification configuration file, which specifies specifications macros of the C array>
            Refer to libcompiler/asn1rs-cli/examples/limits.schema.json to learn about the schema of the specification file.

    -A, --long-abbrs <Path to the abbreviations table that supports whole word matching>
            Refer to libcompiler/asn1rs-cli/examples/long-abbrs.csv for the sample file.

    -m, --mode <Compilation mode (full|noinf)>
            full: generates source code of interfaces and tables. noinf: generates only source code of tables. The default value is noinf.

    -p, --prefix <Prefix of the generated C code symbol>
            The name is case-insensitive.

    -a, --short-abbrs <Path to the abbreviations table that supports single word matching>
            Refer to libcompiler/asn1rs-cli/examples/short-abbrs.csv for the sample file.

    -T, --try-compile <Relative path of libcodec, for example, ../libcodec>
            Tries to compile and generate code. The target language can only be C or C++, and the compiler is GCC.

Example

Convert an ASN.1 script test.asn into a C code file in BER format.

1. The content of the test.asn script is as follows:

   MyModule DEFINITIONS AUTOMATIC TAGS ::= BEGIN 
   
   MyType ::= SEQUENCE { 
       boolType BOOLEAN, 
       intType INTEGER(0..128), 
       enumType ENUMERATED { a, b }, 
       bitStrType BIT STRING(SIZE(0..128)), 
       octStrType OCTET STRING(SIZE(0..64)), 
       seqOfType SEQUENCE OF INTEGER, 
       choiceType CHOICE { 
           a INTEGER(0..3), 
           b BOOLEAN 
       } 
   } 
   
   END

2. Run the asn1rs-cli command to perform the conversion.

   ./asn1rs-cli -i test.asn -m ber cc -m full 

   The generated code file is stored in the exports directory.

   exports 
   └── test 
       ├── codec_index.h 
       ├── codec_interfaces.h 
       └── codec_tables.c

   • codec_index.h: defines the unique identifier of each data unit, which will be used in encoding and decoding interfaces.
   • codec_interfaces.h: provides C program interfaces for data description in abstract syntax.
   • codec_tables.c: defines static variables for describing each data type.

   If --values and --testcases are specified, codec_testcases.h, codec_values.c, and codec_values.h are also generated to define and declare the values in the script and generate test cases.