Wiki source code of Running KEITH

Version 11.1 by Soeren Domroes on 2019/04/01 10:44

version	line-number	content
7.1	1	= Running KEITH =
6.1	2
7.1	3
	4
6.1	5	{{toc/}}
	6
5.1	7	== Setting up your eclipse ==
1.1	8
8.1	9	For everything not mentioned here refer to [[Getting Eclipse>>doc:KIELER.Getting Eclipse\|\|shape="rect"]] guide.
1.1	10
5.1	11	Use the installer go to advanced mode, add the KIELER url. Then select first pragmatics and after that semantics (that is very important).
1.1	12
5.1	13	Select the Theia stream for semantics and the Keith stream for pragmatics and use the latest eclipse if possible. Set the targetplatform to photon and finish.
1.1	14
8.1	15	Wait till everything installs and the setup tasks finish. If you have any problems in this stage refer to the [[Getting Eclipse>>doc:KIELER.Getting Eclipse\|\|shape="rect"]] guide.
1.1	16
5.1	17	\\
1.1	18
5.1	19	The setup tasks for Modular Target will fail. Disable it after this happens and execute them again via //Help>Perform Setup Tasks//. Run //clean build//. Several pragmatics projects have error. Just close them and you will be fine.
1.1	20
5.1	21	To run the language server go to //Run Configurations// create a new //eclipse application// run configuration and select //Run an application// and //de.cau.cs.kieler.language.server.LanguageServer//
1.1	22
5.1	23	== [[image:attach:Screenshot from 2019-02-15 14-10-50.png]] ==
1.1	24
5.1	25	\\
1.1	26
5.1	27	You have to edit the arguments too. The Vm arguments host and port are added to connect the LS via socket.
1.1	28
5.1	29	[[image:attach:Screenshot from 2019-02-15 14-13-34.png]]
1.1	30
5.1	31	The default port to which KEITH tries to connect is 5007.
1.1	32
	33	== Setting up a KEITH developer setup... ==
	34
	35	General requirements:
	36
	37	* node
	38	* npm (whatever node installs)
	39	* yarn (latest version)
	40	* Python (2.7.X)
	41	* gcc, g++, and make (for native dependencies of some npm packages)
	42	* [[Visual Studio Code>>url:https://code.visualstudio.com/\|\|shape="rect"]] (latest version)
	43	* a cloned [[keith >>url:https://git.rtsys.informatik.uni-kiel.de/projects/KIELER/repos/keith/browse\|\|shape="rect"]]repository
	44
	45	== ... on linux: ==
	46
	47	(Theia has a [[guide >>url:https://www.theia-ide.org/doc/authoring_extensions\|\|shape="rect"]]for extension development that might be helpful)
	48
	49	install node 8:
	50
	51	{{code}}
	52	curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.5/install.sh \| bash
	53	nvm install 8
	54	{{/code}}
	55
	56	Install python if you haven't (remember: Python 2: , Python 3: ).
	57
	58	{{code language="none"}}
	59	Install yarn (a package manager build on the package manager npm):
	60	{{/code}}
	61
	62	{{{}}}
	63
	64	\\
	65
	66	{{code}}
	67	npm install -g yarn
	68	{{/code}}
	69
	70	\\
	71
	72	== ... on windows: ==
	73
	74	Install [[node 8>>url:https://nodejs.org/download/release/v8.15.0/\|\|shape="rect"]] for windows. I personally used the {{code language="none"}}.msi{{/code}}.
	75
11.1	76	Use that to install windows-build-tools by executing the command in an administrative powershell.
1.1	77
	78	{{code}}
	79	npm install -g windows-build-tools
	80	{{/code}}
	81
	82	This installs make, gcc, g++, python and all this (I am not sure about yarn, anyway you can always install yarn the same way as in the linux description)
	83
11.1	84	=== Known Problems in this step ===
	85
	86	Python is not correctly registered in the path.
	87
1.1	88	== ... on mac: ==
	89
	90	Get a package manager, something like [[brew>>url:https://brew.sh/index_de\|\|shape="rect"]].
	91
	92	Use brew to install all necessary stuff.
	93
	94	Apparently there is an issue with xcode-select: [[Theia developers>>url:https://github.com/theia-ide/theia/blob/master/doc/Developing.md\|\|shape="rect"]] recommend the following:
	95
	96	{{code}}
	97	xcode-select --install
	98	{{/code}}
	99
5.1	100	After doing this for your OS all that is missing is running KEITH (in developer setup) and setting up your eclipse for language server development).
1.1	101
5.1	102	= Stuff that may help =
1.1	103
5.1	104	== Running the already build LS ==
1.1	105
5.1	106	Go to the latest [[Bamboo build>>url:https://rtsys.informatik.uni-kiel.de/bamboo/browse/KISEMA-NSI\|\|shape="rect"]] and go to Artifacts.
1.1	107
5.1	108	[[image:attach:image2019-2-7_17-46-58.png]]
1.1	109
5.1	110	Select Language Server Zip and download the LS and unpack it somewhere.
	111
	112	Locate the kieler.ini file. Depending on the OS it has a different location (linux; toplevel, windows, toplevel, mac: Content/Eclipse/kieler.ini)
	113
	114	Paste the following at the beginning of the ini-file:
	115
1.1	116	{{code language="bash"}}
5.1	117	-application
	118	de.cau.cs.kieler.language.server.LanguageServer
	119	-noSplash
1.1	120	{{/code}}
	121
5.1	122	Since an eclipse application is built, this is needed to start the LS without a splashscreen.
1.1	123
5.1	124	If you want to connect that LS via socket to your Theia application (KEITH) add the following to the vmargs:
3.1	125
5.1	126	{{code}}
	127	-Dport=5007
	128	{{/code}}
1.1	129
5.1	130	5007 is the standard port KEITH is currently connecting to in socket mode. You can find this port in your Theia application at the following location:
1.1	131
5.1	132	Assume you are in the [[keith >>url:https://git.rtsys.informatik.uni-kiel.de/projects/KIELER/repos/keith/browse\|\|shape="rect"]]repository. Go to {{code language="none"}}keith-app{{/code}}, you should see something like this:
1.1	133
5.1	134	[[image:attach:image2019-2-7_17-58-22.png]]
1.1	135
5.1	136	Open the {{code language="none"}}package.json{{/code}}. In the{{code language="none"}} package.json{{/code}} are several scripts defined.
3.1	137
5.1	138	[[image:attach:image2019-2-7_18-0-7.png]]
1.1	139
5.1	140	The {{code language="none"}}LSP_PORT{{/code}} option is used to activate the connection via socket. It is also possible to specify a relative location to a LS via {{code language="none"}}LS_PATH=<path to LS>{{/code}}.
3.1	141
5.1	142	You can also set these options for an already build [[keith electron app>>url:http://rtsys.informatik.uni-kiel.de/~~kieler/files/nightly/sccharts-integration/\|\|shape="rect"]].
3.1	143
1.1	144	\\
	145
5.1	146	== How run KEITH in developer setup (socket) ==
3.1	147
5.1	148	Run the following to build and run KEITH in its developer setup (in socket mode, so the LS has to be started separately)
3.1	149
5.1	150	{{code language="bash"}}
	151	yarn && cd keith-app && yarn run socket
	152	{{/code}}
	153
	154	Per default the KEITH opens on localhost:3000.
	155
	156	It is required to restart the language server if KEITH is restarted, since the diagram view has a problem (since theia-sprotty is used) to reconnect after that.
7.1	157
	158	= Developing for KEITH =
	159
9.1	160	We use java ServiceLoader to register stuff. Here is a small example how a LanguageServerExtension is registered via a ServiceLoader and how it is used:
	161
	162	== ServiceLoader Example ==
	163
	164	This is a LanguageServerExtension. It has to be used in the de.cau.cs.kieler.language.server plugin. Since the language-sever-plugin should not have dependencies to all plugins that define a language server extension dependency inversion is used to prevent that. A ServiceLoader does exactly that.
	165
	166	Here is such an example extension, the KiCoolLanguageServerExtension:
	167
	168	{{code}}
	169	package de.cau.cs.kieler.kicool.ide.language.server
	170
	171
10.1	172	/**
	173	* @author really fancy name
	174	*
	175	*/
9.1	176	@Singleton
	177	class KiCoolLanguageServerExtension implements ILanguageServerExtension, CommandExtension {
	178	// fancy extension stuff
	179	}
	180	{{/code}}
	181
	182	This language server extension is provided by a corresponding contribution, which is later used to access it:
	183
	184	{{code}}
	185	package de.cau.cs.kieler.kicool.ide.language.server
	186
	187	import com.google.inject.Injector
	188	import de.cau.cs.kieler.language.server.ILanguageServerContribution
	189
	190	/**
	191	* @author really fancy name
	192	*
	193	*/
	194	class KiCoolLanguageServerContribution implements ILanguageServerContribution {
	195
	196	override getLanguageServerExtension(Injector injector) {
	197	return injector.getInstance(KiCoolLanguageServerExtension)
	198	}
	199	}
	200	{{/code}}
	201
10.1	202	Create a file called de.cau.cs.kieler.language.server.ILanguageServerContribution in <plugin>/META-INF/services/ (in this example this is de.cau.cs.kieler.kicool.ide). The name of the file refers to the contribution interface that should be used to provide the contribution. The content of the file is the following:
9.1	203
10.1	204	{{code}}
	205	de.cau.cs.kieler.kicool.ide.language.server.KiCoolLanguageServerContribution
	206	{{/code}}
	207
11.1	208	This is the fully qualified name of the contribution written earlier.
10.1	209
11.1	210	The language server uses all LanguageServerExtensions like this:
	211
	212	{{code}}
	213	var iLanguageServerExtensions = <Object>newArrayList(languageServer) // list of all language server extensions
	214	for (lse : KielerServiceLoader.load(ILanguageServerContribution)) { // load all contributions
	215	iLanguageServerExtensions.add(lse.getLanguageServerExtension(injector))
	216	}
	217	{{/code}}
	218
	219	The resulting list of implementions is used to add the extensions to the language server.
	220
7.1	221	== Register an extension (on server side) ==
	222
11.1	223	See example above for ServiceLoader and initial stuff.
7.1	224
11.1	225	What is still missing are the contents of the CommandExtension implemented by the KiCoolLanguageServerExtension. This is an interface defining all additional commands. The CommandExtension looks like this.
	226
	227	{{code}}
	228	package de.cau.cs.kieler.kicool.ide.language.server
	229
	230	import java.util.concurrent.CompletableFuture
	231	import org.eclipse.lsp4j.jsonrpc.services.JsonRequest
	232	import org.eclipse.lsp4j.jsonrpc.services.JsonSegment
	233
	234	/**
	235	* Interface to the LSP extension commands
	236	*
	237	* @author really fancy name
	238	*
	239	*/
	240	@JsonSegment('keith/kicool')
	241	interface CommandExtension {
	242
	243	/**
	244	* Compiles file given by uri with compilationsystem given by command.
	245	*/
	246	@JsonRequest('compile')
	247	def CompletableFuture<CompilationResults> compile(String uri, String clientId, String command, boolean inplace);
	248
	249	/**
	250	* Build diagram for snapshot with id index for file given by uri. Only works, if the file was already compiled.
	251	*/
	252	@JsonRequest('show')
	253	def CompletableFuture<String> show(String uri, String clientId, int index)
	254
	255	/**
	256	* Returns all compilation systems which are applicable for the file at given uri.
	257	*
	258	* @param uri URI as string to get compilation systems for
	259	* @param filter boolean indicating whether compilation systems should be filtered
	260	*/
	261	@JsonRequest('get-systems')
	262	def CompletableFuture<Object> getSystems(String uri, boolean filterSystems)
	263	}
	264	{{/code}}
	265
	266	This defines three json-rpc commands: "keith/kicool/compile", "keith/kicool/show", "keith/kicool/get-systems". These are implemented in KiCoolLanguageServerExtension.
	267
	268	== Register and calling an extension (on client side) ==
	269
	270	Language server extension do not have to be registered on the client side. It is just called.
	271
	272	You can send a request or a notification to the language server like this:
	273
	274	{{code}}
	275	const lclient = await this.client.languageClient
	276	const snapshotsDescriptions: CodeContainer = await lclient.sendRequest("keith/kicool/compile", [uri, KeithDiagramManager.DIAGRAM_TYPE + '_sprotty', command,
	277	this.compilerWidget.compileInplace]) as CodeContainer
	278	// or via a thenable
	279
	280
	281	{{/code}}
	282
	283	\\
	284
7.1	285	== How to send messages ==
	286
	287	== How to write a widget ==

Wiki source code of Running KEITH

Navigation

Quick Links