plugins/org.eclipse.etrice.doc/featuremodel/etrice.codegenerators.featurizer

FeaturizerModel eTriceCodegenerators
	imports "etrice.roomlanguage.featurizer", "etrice.featurizer"


Package CodeGenerators
	description ''''''
	contains CCodeGenerator
	contains JavaCodeGenerator
	contains CPPCodeGenerator
;

Feature CCodeGenerator
	shortName '''C Code Generator'''
	description ''''''

	contains GenerationOptions
	contains MSCLogging
	contains DataLogging

	stable
;
Feature JavaCodeGenerator
	shortName '''Java Code Generator'''
	description ''''''

	contains GenerationOptions
	contains MSCLogging

	stable
;
Feature CPPCodeGenerator
	shortName '''C++ Code Generator'''
	description ''''''

	prototype
;

Feature GenerationOptions
	description '''Mechanism to adjust the generation.'''
	text '''
		Options for generation are configured in the launch configuration or in case of standalone generation via command line.
		A list of available options:

		- generate as library
		- generate documentation
		- generate instrumentation for MSC generation
		- generate instrumentation for data logging
		- override output directories
		- debug options
	'''
	stable
	;

Feature MSCLogging
	description '''Runtime logger for event-driven Messages, represented as a Message Sequence Chart.'''
	text '''
		The MSCLogging is activated by default, but can be set manually in the [GenerationOptions][]. The output file is created upon regular termination of the application. The resulting file can be found in the logging directory and has the name *msc.seq*, which can be open with the free open source tool [Trace2UML](http://trace2uml.stage.tigris.org/).

		![MSCLogging](images/300-MSCLogging.png)
	'''

	uses GenerationOptions
	stable
;

Feature DataLogging
	description '''Runtime logger for data-driven Messages with primitive data.'''
	text '''
		The DataLogging uses an annotation to configure the generated instrumentation:

		```room
		@DataLogging(pathlist = "/portInstancePath,/portInstancePath,..")
		```

		Where `pathlist` is a string specifying a list of port instances which should be instrumented for data logging:

		- the path of a port instance starts with the name of the [LogicalSystem][] and thus consists of at least 4 following segments
		`/portInstancePath` = `/LogicalSystem/SubSystemRef/ActorRef/Port`
		- multiple paths are separated through comma (`,`), but avoid any whitespace
		- the [Port][] must be conjugated and it´s [ProtocolClass][] has to be data-driven
		- only the first Message having primitive or enum typed data is considered

		The logging status can be verified in the generation console. It will output an overview of all accepted ports. In the [GenerationOptions][] is possible to (de)activate the data logging and thus ignoring the presence of the annotation.

		At runtime the data values will then be logged

		- into a file *log/SubSystemRef.data.csv*
		- it contains one column for each port instance
		- and a new row for every polling cycle, containing all readout data values
		- the first column is used to number the cycles

		Multi-Threading is not supported, the system must have not more than one polled/async physical thread.


		The built-in **Gnuplot script generator** provides a convenient way to visualize the logged data. It generates a gnuplot script that can be used to create graphs from the logged data values.

		* Download Gnuplot from [www.gnuplot.info](http://www.gnuplot.info/) and add it to the environment variable *PATH* (e.g. `C:\Program Files\gnuplot\bin;`)
		* Use the `@Gnuplot` and `@GnuplotGraph` to configure the script generation (see example)
		* The generated artifacts can be found in *src-gen/gnuplot*:
			- *xxx.csv-script.plt* - the gnuplot script, the resulting images are place in folder *log/*
			- *create_gnuplot.launch* - a launch configuration to call gnuplot executable with above script

	'''
	example '''
		```room
		import room.basic.annotations.* from "../../org.eclipse.etrice.modellib.c/model/Annotations.room"

		LogicalSystem Logging {
		 	SubSystemRef main: MainSubSystem
		}

		SubSystemClass MainSubSystem {
		 	@DataLogging(pathlist = "/Logging/main/actorRef1/port1")
		 	@Gnuplot(format="pngcairo", outputfile="main.data.png", width=1800, height=600, fontsize=10)
			@GnuplotGraph(
				paths="/Logging/main/actorRef1/port1",
				xtics=100, mxtics=4, ymin=-1.2, ymax=1.2
			)
		```

		Logged data values in .csv format:
		```
		 , /LogSys/subSystemRef/rootActor/serverInst/output, /LogSys/subSystemRef/rootActor/clientInst/output
		0, 0.000000											,0.000000
		1, 0.000000											,0.100000
		2, 0.099833											,0.200000
		3, 0.198669											,0.300000
		4, 0.295520											,0.400000
		5, 0.389418											,0.500000
		[...]
		```

		Resulting graph created from generated gnuplot script:
		![Gnuplot example](images/300-Gnuplot.png)
	'''

	uses Annotation
	prototype
;

//Feature ^DocumentationGenerator
//	description '''A LaTeX documentation generator from eTrice models.'''
//	uses GenerationOptions
//	prototype
//;