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