compiler2/compiler.1

   1 .TH compiler 1 "October 2014" "Ericsson Telecom AB" "TTCN-3 Tools"
   2 .SH NAME
   3 compiler \- TTCN-3 and ASN.1 to C++ translator
   4 .SH SYNOPSIS
   5 .B compiler
   6 .RB "[\| " \-abcdEfgijlLMnpqrRsStuwxXyY " \|]"
   7 .RB "[\| " \-V
   8 .IR " verb_level" " \|]"
   9 .RB "[\| " \-K
  10 .IR " file" " \|]"
  11 .RB "[\| " \-z
  12 .IR " file" " \|]"
  13 .RB "[\| " \-o
  14 .IR " dir" " \|]"
  15 .RB "[\| " \-P
  16 .IR " top_level_pdu" " \|] ..."
  17 .RB "[\| " \-Q
  18 .IR "n" " \|] "
  19 .RB "[\| " \-U
  20 .IR "none|type" " \|] "
  21 .RB "[\| " \-T " \|]"
  22 module.ttcn ...
  23 .RB "[\| " \-A " \|]"
  24 module.asn ...
  25 [\| \- module.ttcn ... module.asn ... \|]
  26 .br
  27 or
  28 .br
  29 .B compiler
  30 .B \-v
  31 .br
  32 or
  33 .br
  34 .B compiler \-\-ttcn2json
  35 .RB "[\| " \-jf " \|]"
  36 .RB "[\| " \-T " \|]"
  37 module.ttcn ...
  38 .RB "[\| " \-A " \|]"
  39 module.asn ...
  40 .RB "[\| " \-
  41 schema.json
  42 .RB " \|]"
  43 .SH DESCRIPTION
  44 This manual page is a quick reference for the TTCN-3 and ASN.1 to C++ (or JSON schema)
  45 compiler of the TTCN-3 Test Executor. It only summarizes the meaning of
  46 all command line options. For more details please consult the
  47 .B Programmer's Technical Reference for TITAN TTCN-3 Test Executor.
  48 .SH OPTIONS
  49 The following options are supported (in alphabetical order):
  50 .TP 10
  51 .BI \-A " file"
  52 Forces the interpretation of
  53 .I file
  54 as an
  55 .I ASN.1 module.
  56 It is useful when automatic module type detection fails
  57 due to some strange language constructs. The option takes exactly one file
  58 name as argument. The option must be repeated when used with multiple files.
  59 See also: option
  60 .B \-T.
  61 .TP
  62 .B \-a
  63 Force
  64 .I XER
  65 in ASN.1 files
  66 .TP
  67 .B \-b
  68 Disables the generation of
  69 .I BER
  70 encoder/decoder routines for all ASN.1 types.
  71 .TP
  72 .B \-B
  73 Allows the selected field in a union value to be unbound, when setting module
  74 parameters (legacy behavior). A warning is displayed whenever a union value
  75 receives an unbound selected field and when a union with an unbound selected field
  76 is copied.
  77 .TP
  78 .B \-c
  79 Write out
  80 .I checksums
  81 in case of error
  82 .TP
  83 .B \-d
  84 Treat ASN.1
  85 .I SEQUENCE/SET
  86 fields with DEFAULT values as
  87 .I omit
  88 in TTCN-3.
  89 .TP
  90 .B \-E
  91 Instructs the variant attribute parser to display warnings instead of errors
  92 for unrecognized/erroneous attributes.
  93 .TP
  94 .B \-f
  95 Forces the compiler to
  96 .I overwrite
  97 the output files even if they exist or are unchanged.
  98 .TP
  99 .B \-g
 100 The compiler error/warning messages will contain only the starting
 101 line number and column, in a format compatible with th GNU compiler (gcc).
 102 .B \-g
 103 takes precedence over
 104 .B \-i
 105 if both are specified.
 106 .TP
 107 .B \-i
 108 The compiler error/warning messages
 109 will contain only the
 110 .I line numbers,
 111 the column numbers will remain hidden. This option provides backward
 112 compatibility with the error message format of earlier versions.
 113 .TP
 114 .B \-j
 115 Disables JSON encoder/decoder functions.
 116 .TP
 117 .BI \-K " file"
 118 Enables selective code coverage.
 119 .TP
 120 .B \-l
 121 Instructs the compiler to generate source file and line information (i.e.
 122 .I #line
 123 directives) into the output C++ code so that the C++ compiler error
 124 messages refer back to the lines of original TTCN-3 input module.
 125 .br
 126 This option is
 127 .I obsolete
 128 and will be removed in future versions as the
 129 compiler does not generate erroneous C++ code because of the full
 130 semantic analysis.
 131 .TP
 132 .B \-L
 133 Instructs the compiler to add source file and line
 134 .I source file
 135 and
 136 .I line number
 137 information into the generated code to be included in the
 138 .I log
 139 during execution.
 140 .br
 141 This option is only a prerequisite for logging the source code information.
 142 Options
 143 .I SourceInfoFormat
 144 and
 145 .I LogEntityName
 146 have also to be set appropriately in section
 147 .I [LOGGING]
 148 of the run-time configuration file.
 149 .br
 150 Usage of this option a bit enlarges the size of the generated code and slightly
 151 reduces execution speed. This flag is not recommended when the TTCN-3 test
 152 suite is used for load generation.
 153 .TP
 154 .B \-M
 155 Allows the use of the value
 156 .B omit
 157 in template lists and complemented template lists (legacy behavior).
 158 If set, an omitted field will match a template list, if the value
 159 .B omit
 160 appears in the list, and it will match a complemented template list, if
 161 .B omit
 162 is not in the list (the
 163 .B ifpresent
 164 attribute can still be used for matching omitted fields). This also affects the
 165 .B ispresent
 166 operation and the
 167 .B present
 168 template restriction accordingly.
 169 .TP
 170 .B \-n
 171 Activates the debugger and generates extra code for storing debug information.
 172 .TP
 173 .BI \-o " dir"
 174 The output files (including Test Port skeletons) will be placed into
 175 the directory specified by
 176 .I dir.
 177 The current working directory is the default otherwise.
 178 .TP
 179 .B \-p
 180 Instructs the compiler only to
 181 .I parse
 182 the given TTCN-3 and ASN.1 modules. This will detect only the syntax errors
 183 because semantic checkings are
 184 .I not
 185 performed. The presence of all imported modules is not necessary thus it is
 186 allowed (and recommended) to parse the modules one-by-one.
 187 .br
 188 All options that influence the code generation are silently ignored when used
 189 together with
 190 .B \-p.
 191 .br
 192 .B Note:
 193 This option includes complete syntax checks for TTCN-3 modules, but in ASN.1
 194 there are some special constructs (e.g. the user-defined syntaxes) that cannot
 195 be even parsed without semantic analysis. So there is no guarantee that an ASN.1
 196 module is free of syntax errors if it was analyzed with compiler using the
 197 .B -p
 198 flag.
 199 .TP
 200 .BI \-P " top_level_pdu" ...
 201 Defines a top-level pdu.
 202 .I top_level_pdu
 203 must have the following format:
 204 .I modulename.identifier.
 205 If this switch is used, then only the defined top-level PDU(s) and the
 206 referenced assignments are checked and included in code generation, the
 207 other ASN.1 assignments are skipped.
 208 .TP
 209 .B \-q
 210 .I Quiet
 211 mode. Equivalent with
 212 .B \-V 0.
 213 .TP
 214 .B \-Qn
 215 .I Quits
 216 after
 217 .B n
 218 errors.
 219 .TP
 220 .B \-r
 221 Disables the generation of
 222 .I RAW
 223 encoder/decoder routines for all TTCN-3 types.
 224 .TP
 225 .B \-R
 226 Use function test runtime (TITAN_RUNTIME_2). The compiler will generate source
 227 code for use with function test runtime.
 228 .TP
 229 .B \-s
 230 Instructs the compiler to parse the given TTCN-3 and ASN.1 modules and perform
 231 .I semantic analysis
 232 on them, but
 233 .I not
 234 to generate C++ output. The list of given modules shall be complete so it is
 235 not allowed to import from a module that is not in the list. All options that
 236 influence the code generation are silently ignored when used together with
 237 .B \-s.
 238 .TP
 239 .B \-S
 240 .I Suppresses
 241 context information.
 242 .TP
 243 .B \-t
 244 Generates
 245 .I Test Port
 246 skeleton header and source files for all port types that can be found in
 247 TTCN-3 modules. Existing Test Port files will not be overwritten unless the
 248 .B \-f
 249 option is used.
 250 .TP
 251 .BI \-T " file"
 252 Forces the interpretation of
 253 .I file
 254 as a
 255 .I TTCN-3 module.
 256 See also: option
 257 .B \-A.
 258 .TP
 259 .B \-u
 260 Forces the compiler to do
 261 .I duplicate underscore
 262 characters in all output file names. This option turns on the
 263 compatibility mode with versions 1.1 or earlier.
 264 .TP
 265 .BI \-U " none|type"
 266 Selects code splitting mode for the generated C++ code.
 267 .TP
 268 .B \-v
 269 Prints
 270 .I version
 271 and license key information and exits.
 272 .TP
 273 .BI \-V " verb_level"
 274 Sets the verbosity bit-mask directly to
 275 .I verb_level
 276 (where
 277 .I verb_level
 278 is a decimal value between 0 and 65535).
 279 .br
 280 .sp 1
 281 Meaning of bits:
 282 .P
 283 .RS 10
 284 .PD 0
 285 .TP 10
 286 .B 1:
 287 "NOT SUPPORTED" messages.
 288 .TP
 289 .B 2:
 290 WARNING messages.
 291 .TP
 292 .B 4:
 293 NOTIFY messages.
 294 .TP
 295 .B 32|16|8:
 296 DEBUG messages.
 297 .br
 298 The debug-bits act like a 3-bits-length number, so the debug level has
 299 a value between 0 and 7. It is useful in case of abnormal program termination.
 300 .PD
 301 .RE
 302 .P
 303 .TP 10
 304 .B \-w
 305 Suppresses all
 306 .I warning
 307 messages. Equivalent with
 308 .B \-V 4.
 309 .TP
 310 .B \-x
 311 Disables the generation of
 312 .I TEXT
 313 encoder/decoder routines for all TTCN-3 types.
 314 .TP
 315 .B \-X
 316 Disable
 317 .I XER
 318 encoder/decoder functions
 319 .TP
 320 .B \-y
 321 Disable
 322 .I subtype
 323 checking
 324 .TP
 325 .B \-Y
 326 Enforces legacy behaviour of the "out" function parameters (see refguide).
 327 .TP
 328 .BI \-z " file"
 329 Enables profiling and code coverage in the selected TTCN-3 files. The
 330 .I file
 331 argument contains a list of TTCN-3 files separated by new lines. Each TTCN-3 file must be among the compiler's TTCN-3 file arguments.
 332 .TP
 333 .B \-
 334 The single dash character as command line argument controls the
 335 .I selective code generation
 336 option.
 337 After the list of all TTCN-3 and ASN.1 modules a subset of these files can
 338 be given separated by a dash. This option instructs the compiler to parse all
 339 modules, perform the semantic analysis on the entire module hierarchy, but
 340 generate code
 341 .I only
 342 for those modules that are listed after the dash again.
 343 .br
 344 It is not allowed to specify a file name after the dash that was not present
 345 in the list before the dash. If the single dash is not present in the command
 346 line the compiler will generate code for
 347 .I all
 348 modules.
 349 .TP
 350 .B \-\-ttcn2json
 351 Generates a JSON schema from the types defined in the specified TTCN-3 and ASN.1 modules.
 352 Must always be the first compiler option. From the previously listed options only
 353 .B \-T
 354 and
 355 .B \-A
 356 can be used, instead the JSON schema generator has options of its own:
 357 .TP
 358 .B \-j
 359 Only types that have JSON coding enabled are included in the schema.
 360 .TP
 361 .B \-f
 362 The schema only validates types that have a JSON encoding or decoding method declared.
 363 .TP
 364 .BI \- " file"
 365 The single dash character as command line argument specifies the name of the generated
 366 JSON schema file. If it is not present, then the schema file name is generated from
 367 the name of the first input file (by replacing its suffix with
 368 .I \.json
 369 or appending
 370 .I \.json
 371 to the end of the file).
 372 .SH EXIT STATUS
 373 The compiler exits with a status of zero when no errors were encountered
 374 during its operation. A status of one will be returned if syntax or
 375 semantic errors were detected in the input modules.
 376 .SH ENVIRONMENT VARIABLES
 377 .TP
 378 .SM
 379 TTCN3_DIR
 380 The installation directory where the uncompressed binary package of
 381 TTCN-3 Test Executor can be found.
 382 .TP
 383 .SM
 384 TTCN3_LICENSE_FILE
 385 It shall point to the
 386 .I file
 387 .RB ( NB:
 388 .I not
 389 to its directory) that contains the personalized license key for the
 390 current user or host.
 391 .SH BUGS
 392 The compiler does not support all constructs of TTCN-3 Core Language and ASN.1.
 393 It reports an error when encountering an unsupported language element.
 394 The detailed list of deficiencies and language extensions can be found in the
 395 referenced documentation.
 396 .LP
 397 For trouble reporting use the tool
 398 .BR "MHWEB" "."
 399 For TR writers guide please visit the web page:
 400 .I http://ttcn.ericsson.se.
 401 .SH SEE ALSO
 402 .TP
 403 .SM
 404 Ericsson document 2/198 17-CRL 113 200 Uen:
 405 .B Programmer's Technical Reference for TITAN TTCN-3 Test Executor
 406 .TP
 407 .SM
 408 ETSI Standard ES 201-873-1:
 409 .B Testing and Test Control Notation: TTCN-3 Core Language
 410 .TP
 411 .SM
 412 ITU-T Recommendations X.680-683:
 413 .B Abstract Syntax Notation One (ASN.1)
 414 .SH AUTHOR
 415 This manpage is written by Janos Zoltan Szabo, Ericsson Telecom AB
 416 .br
 417 Copyright (c) 2000-2016 Ericsson Telecom AB
 418 .br
 419 All rights reserved. This program and the accompanying materials
 420 are made available under the terms of the Eclipse Public License v1.0
 421 which accompanies this distribution, and is available at
 422 .br
 423 http://www.eclipse.org/legal/epl-v10.html