[deliverable/titan.core.git] / compiler2 / compiler.1

.TH compiler 1 "October 2014" "Ericsson Telecom AB" "TTCN-3 Tools"
.SH NAME
compiler \- TTCN-3 and ASN.1 to C++ translator
.SH SYNOPSIS
.B compiler
.RB "[\| " \-abcdfgijlLMpqrRsStuwxXyY " \|]"
.RB "[\| " \-V
.IR " verb_level" " \|]"
.RB "[\| " \-K
.IR " file" " \|]"
.RB "[\| " \-z
.IR " file" " \|]"
.RB "[\| " \-o
.IR " dir" " \|]"
.RB "[\| " \-P
.IR " top_level_pdu" " \|] ..."
.RB "[\| " \-Q
.IR "n" " \|] "
.RB "[\| " \-U
.IR "none|type" " \|] "
.RB "[\| " \-T " \|]"
module.ttcn ...
.RB "[\| " \-A " \|]"
module.asn ...
[\| \- module.ttcn ... module.asn ... \|]
.br
or
.br
.B compiler
.B \-v
.br
or
.br
.B compiler \-\-ttcn2json
.RB "[\| " \-jf " \|]"
.RB "[\| " \-T " \|]"
module.ttcn ...
.RB "[\| " \-A " \|]"
module.asn ...
.RB "[\| " \-
schema.json
.RB " \|]"
.SH DESCRIPTION
This manual page is a quick reference for the TTCN-3 and ASN.1 to C++ (or JSON schema)
compiler of the TTCN-3 Test Executor. It only summarizes the meaning of
all command line options. For more details please consult the
.B Programmer's Technical Reference for TITAN TTCN-3 Test Executor.
.SH OPTIONS
The following options are supported (in alphabetical order):
.TP 10
.BI \-A " file"
Forces the interpretation of
.I file
as an
.I ASN.1 module.
It is useful when automatic module type detection fails
due to some strange language constructs. The option takes exactly one file
name as argument. The option must be repeated when used with multiple files.
See also: option
.B \-T.
.TP
.B \-a
Force
.I XER
in ASN.1 files
.TP
.B \-b
Disables the generation of
.I BER
encoder/decoder routines for all ASN.1 types.
.TP
.B \-c
Write out
.I checksums
in case of error
.TP
.B \-d
Treat ASN.1
.I SEQUENCE/SET
fields with DEFAULT values as
.I omit
in TTCN-3.
.TP
.B \-f
Forces the compiler to
.I overwrite
the output files even if they exist or are unchanged.
.TP
.B \-g
The compiler error/warning messages will contain only the starting
line number and column, in a format compatible with th GNU compiler (gcc).
.B \-g
takes precedence over
.B \-i
if both are specified.
.TP
.B \-i
The compiler error/warning messages
will contain only the
.I line numbers,
the column numbers will remain hidden. This option provides backward
compatibility with the error message format of earlier versions.
.TP
.B \-j
Disables JSON encoder/decoder functions.
.TP
.BI \-K " file"
Enables selective code coverage.
.TP
.B \-l
Instructs the compiler to generate source file and line information (i.e.
.I #line
directives) into the output C++ code so that the C++ compiler error
messages refer back to the lines of original TTCN-3 input module.
.br
This option is
.I obsolete
and will be removed in future versions as the
compiler does not generate erroneous C++ code because of the full
semantic analysis.
.TP
.B \-L
Instructs the compiler to add source file and line
.I source file
and
.I line number
information into the generated code to be included in the
.I log
during execution.
.br
This option is only a prerequisite for logging the source code information.
Options
.I SourceInfoFormat
and
.I LogEntityName
have also to be set appropriately in section
.I [LOGGING]
of the run-time configuration file.
.br
Usage of this option a bit enlarges the size of the generated code and slightly
reduces execution speed. This flag is not recommended when the TTCN-3 test
suite is used for load generation.
.TP
.B \-M
Allows the use of the value
.B omit
in template lists and complemented template lists (legacy behavior).
If set, an omitted field will match a template list, if the value
.B omit
appears in the list, and it will match a complemented template list, if
.B omit
is not in the list (the
.B ifpresent
attribute can still be used for matching omitted fields). This also affects the
.B ispresent
operation and the
.B present
template restriction accordingly.
.TP
.BI \-o " dir"
The output files (including Test Port skeletons) will be placed into
the directory specified by
.I dir.
The current working directory is the default otherwise.
.TP
.B \-p
Instructs the compiler only to
.I parse
the given TTCN-3 and ASN.1 modules. This will detect only the syntax errors
because semantic checkings are
.I not
performed. The presence of all imported modules is not necessary thus it is
allowed (and recommended) to parse the modules one-by-one.
.br
All options that influence the code generation are silently ignored when used
together with
.B \-p.
.br
.B Note:
This option includes complete syntax checks for TTCN-3 modules, but in ASN.1
there are some special constructs (e.g. the user-defined syntaxes) that cannot
be even parsed without semantic analysis. So there is no guarantee that an ASN.1
module is free of syntax errors if it was analyzed with compiler using the
.B -p
flag.
.TP
.BI \-P " top_level_pdu" ...
Defines a top-level pdu.
.I top_level_pdu
must have the following format:
.I modulename.identifier.
If this switch is used, then only the defined top-level PDU(s) and the
referenced assignments are checked and included in code generation, the
other ASN.1 assignments are skipped.
.TP
.B \-q
.I Quiet
mode. Equivalent with
.B \-V 0.
.TP
.B \-Qn
.I Quits
after 
.B n
errors.
.TP
.B \-r
Disables the generation of
.I RAW
encoder/decoder routines for all TTCN-3 types.
.TP
.B \-R
Use function test runtime (TITAN_RUNTIME_2). The compiler will generate source
code for use with function test runtime.
.TP
.B \-s
Instructs the compiler to parse the given TTCN-3 and ASN.1 modules and perform
.I semantic analysis
on them, but
.I not
to generate C++ output. The list of given modules shall be complete so it is
not allowed to import from a module that is not in the list. All options that
influence the code generation are silently ignored when used together with
.B \-s.
.TP
.B \-S
.I Suppresses 
context information.
.TP
.B \-t
Generates
.I Test Port
skeleton header and source files for all port types that can be found in
TTCN-3 modules. Existing Test Port files will not be overwritten unless the
.B \-f
option is used.
.TP
.BI \-T " file"
Forces the interpretation of
.I file
as a
.I TTCN-3 module.
See also: option
.B \-A.
.TP
.B \-u
Forces the compiler to do
.I duplicate underscore
characters in all output file names. This option turns on the
compatibility mode with versions 1.1 or earlier.
.TP
.BI \-U " none|type"
Selects code splitting mode for the generated C++ code.
.TP
.B \-v
Prints
.I version
and license key information and exits.
.TP
.BI \-V " verb_level"
Sets the verbosity bit-mask directly to
.I verb_level
(where
.I verb_level
is a decimal value between 0 and 65535).
.br
.sp 1
Meaning of bits:
.P
.RS 10
.PD 0
.TP 10
.B 1:
"NOT SUPPORTED" messages.
.TP
.B 2:
WARNING messages.
.TP
.B 4:
NOTIFY messages.
.TP
.B 32|16|8:
DEBUG messages.
.br
The debug-bits act like a 3-bits-length number, so the debug level has
a value between 0 and 7. It is useful in case of abnormal program termination.
.PD
.RE
.P
.TP 10
.B \-w
Suppresses all
.I warning
messages. Equivalent with
.B \-V 4.
.TP
.B \-x
Disables the generation of
.I TEXT
encoder/decoder routines for all TTCN-3 types.
.TP
.B \-X
Disable
.I XER
encoder/decoder functions
.TP
.B \-y
Disable
.I subtype
checking
.TP
.B \-Y
Enforces legacy behaviour of the "out" function parameters (see refguide).
.TP
.BI \-z " file"
Enables profiling and code coverage in the selected TTCN-3 files. The
.I file
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.
.TP
.B \-
The single dash character as command line argument controls the
.I selective code generation
option.
After the list of all TTCN-3 and ASN.1 modules a subset of these files can
be given separated by a dash. This option instructs the compiler to parse all
modules, perform the semantic analysis on the entire module hierarchy, but
generate code
.I only
for those modules that are listed after the dash again.
.br
It is not allowed to specify a file name after the dash that was not present
in the list before the dash. If the single dash is not present in the command
line the compiler will generate code for
.I all
modules.
.TP
.B \-\-ttcn2json
Generates a JSON schema from the types defined in the specified TTCN-3 and ASN.1 modules.
Must always be the first compiler option. From the previously listed options only
.B \-T
and
.B \-A
can be used, instead the JSON schema generator has options of its own:
.TP
.B \-j
Only types that have JSON coding enabled are included in the schema.
.TP
.B \-f
The schema only validates types that have a JSON encoding or decoding method declared.
.TP
.BI \- " file"
The single dash character as command line argument specifies the name of the generated
JSON schema file. If it is not present, then the schema file name is generated from
the name of the first input file (by replacing its suffix with
.I \.json
or appending
.I \.json
to the end of the file).
.SH EXIT STATUS
The compiler exits with a status of zero when no errors were encountered
during its operation. A status of one will be returned if syntax or
semantic errors were detected in the input modules.
.SH ENVIRONMENT VARIABLES
.TP
.SM
TTCN3_DIR
The installation directory where the uncompressed binary package of
TTCN-3 Test Executor can be found.
.TP
.SM
TTCN3_LICENSE_FILE
It shall point to the
.I file
.RB ( NB:
.I not
to its directory) that contains the personalized license key for the
current user or host.
.SH BUGS
The compiler does not support all constructs of TTCN-3 Core Language and ASN.1.
It reports an error when encountering an unsupported language element.
The detailed list of deficiencies and language extensions can be found in the
referenced documentation.
.LP
For trouble reporting use the tool
.BR "MHWEB" "."
For TR writers guide please visit the web page:
.I http://ttcn.ericsson.se.
.SH SEE ALSO
.TP
.SM
Ericsson document 2/198 17-CRL 113 200 Uen:
.B Programmer's Technical Reference for TITAN TTCN-3 Test Executor
.TP
.SM
ETSI Standard ES 201-873-1:
.B Testing and Test Control Notation: TTCN-3 Core Language
.TP
.SM
ITU-T Recommendations X.680-683:
.B Abstract Syntax Notation One (ASN.1)
.SH AUTHOR
This manpage is written by Janos Zoltan Szabo, Ericsson Telecom AB
.br
Copyright (c) 2000-2015 Ericsson Telecom AB
.br
All rights reserved. This program and the accompanying materials
are made available under the terms of the Eclipse Public License v1.0
which accompanies this distribution, and is available at
.br
http://www.eclipse.org/legal/epl-v10.html
Commit	Line	Data
970ed795 EL	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
3abe9331	6	.RB "[\\| " \-abcdfgijlLMpqrRsStuwxXyY " \\|]"
970ed795 EL	7	.RB "[\\| " \-V
	8	.IR " verb_level" " \\|]"
	9	.RB "[\\| " \-K
	10	.IR " file" " \\|]"
a38c6d4c	11	.RB "[\\| " \-z
a38c6d4c	12	.IR " file" " \\|]"
970ed795 EL	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
af710487	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 " \\|]"
970ed795	43	.SH DESCRIPTION
af710487	44	This manual page is a quick reference for the TTCN-3 and ASN.1 to C++ (or JSON schema)
970ed795 EL	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
3abe9331	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
970ed795 EL	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
a38c6d4c	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
970ed795 EL	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.
af710487	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).
970ed795 EL	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
3abe9331	404	Copyright (c) 2000-2015 Ericsson Telecom AB
970ed795 EL	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