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