Skip to content

Commit 91abf81

Browse files
king-tylerking-tyler
authored
Add README (#21)
1 parent 99708ca commit 91abf81

File tree

1 file changed

+165
-0
lines changed

1 file changed

+165
-0
lines changed

‎README.md

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# Gradle Xtext Generator Plugins ![Build](https://github.com/zxhr/gradle-xtext-generator/workflows/Build/badge.svg)
2+
3+
gradle-xtext-generator is a set of Gradle plugins for configuring and using the
4+
[Xtext Language Generator](https://www.eclipse.org/Xtext/documentation/302_configuration.html#generator) seamlessly
5+
within Gradle. This includes:
6+
7+
* Automatically configuring the
8+
[XtextProjectConfig](https://www.eclipse.org/Xtext/documentation/302_configuration.html#project-configuration)
9+
based on how the [Gradle Project](https://docs.gradle.org/current/dsl/org.gradle.api.Project.html) and
10+
[JavaPlugin](https://docs.gradle.org/current/userguide/java_plugin.html) are configured.
11+
* [Xtext Language Configuration](https://www.eclipse.org/Xtext/documentation/302_configuration.html#language-configuration)
12+
and [CodeConfig](https://www.eclipse.org/Xtext/documentation/302_configuration.html#other-general-configuration)
13+
are configured inside the `build.gradle` obviating the need to use an `.mwe2` file.
14+
* Generates the project's `build.properties` when imported into Eclipse so that dsl project can be launched and tested
15+
within Eclipse PDE.
16+
17+
## Usage
18+
19+
gradle-xtext-generator provides the following plugins:
20+
21+
* `com.github.zxhr.xtext-generator-root-project` - applied to the root Gradle project and used to configure the
22+
[Xtext Language Configuration](https://www.eclipse.org/Xtext/documentation/302_configuration.html#language-configuration)
23+
and [CodeConfig](https://www.eclipse.org/Xtext/documentation/302_configuration.html#other-general-configuration).
24+
* `com.github.zxhr.xtext-generator-runtime` - configures the XtextProjectConfig's runtime project from the Gradle
25+
project the plugin is applied to.
26+
* `com.github.zxhr.xtext-generator-runtime-test` - configures the XtextProjectConfig's runtimeTest project from the
27+
Gradle project the plugin is applied to.
28+
* `com.github.zxhr.xtext-generator-generic-ide` - configures the XtextProjectConfig's genericIde project from the
29+
Gradle project the plugin is applied to.
30+
* `com.github.zxhr.xtext-generator-eclipse-plugin` - configures the XtextProjectConfig's eclipsePlugin project from the
31+
Gradle project the plugin is applied to.
32+
* `com.github.zxhr.xtext-generator-eclipse-plugin-test` - configures the XtextProjectConfig's eclipsePluginTest project
33+
from the Gradle project the plugin is applied to.
34+
* `com.github.zxhr.xtext-generator-web` - configures the XtextProjectConfig's web project from the Gradle project the
35+
plugin is applied to.
36+
37+
### Example Setup
38+
39+
#### `projectRoot/build.gradle`
40+
```groovy
41+
import org.eclipse.xtext.xtext.generator.StandardLanguage
42+
43+
buildscript {
44+
ext {
45+
xtextVersion = '2.22.0'
46+
}
47+
repositories {
48+
gradlePluginPortal()
49+
}
50+
dependencies {
51+
classpath enforcedPlatform("org.eclipse.xtext:xtext-dev-bom:$xtextVersion")
52+
classpath 'com.github.zxhr:gradle-xtext-generator:<plugin-version>'
53+
classpath "org.eclipse.xtext:org.eclipse.xtext.xtext.generator:$xtextVersion"
54+
classpath "org.eclipse.xtext:org.eclipse.xtext.common.types:$xtextVersion"
55+
classpath 'org.xtext:xtext-gradle-plugin:2.0.8'
56+
}
57+
}
58+
59+
apply plugin: 'com.github.zxhr.xtext-generator-root-project'
60+
apply plugin: 'org.xtext.xtend'
61+
62+
xtextRoot {
63+
language('MyDsl', StandardLanguage) {
64+
grammarUri = file('src/main/xtext/MyDsl.xtext').toURI().toString()
65+
fileExtensions = 'mydsl'
66+
67+
/* Other language configuration */
68+
}
69+
codeConfig {
70+
preferXtendStubs = true // this plugin sets the default to false
71+
}
72+
}
73+
```
74+
75+
#### `projectRoot/my.dsl/build.gradle`
76+
```groovy
77+
plugins {
78+
id 'com.github.zxhr.xtext-generator-runtime'
79+
id 'com.github.zxhr.xtext-generator-runtime-test'
80+
}
81+
82+
dependencies {
83+
implementation platform("org.eclipse.xtext:xtext-dev-bom:$xtextVersion")
84+
implementation "org.eclipse.xtext:org.eclipse.xtext:$xtextVersion"
85+
testImplementation "org.eclipse.xtext:org.eclipse.xtext.testing:$xtextVersion"
86+
testImplementation 'junit:junit:4.12'
87+
}
88+
```
89+
90+
#### `projectRoot/my.dsl.ide/build.gradle`
91+
```groovy
92+
plugins {
93+
id 'com.github.zxhr.xtext-generator-generic-ide'
94+
}
95+
96+
dependencies {
97+
implementation project(':my.dsl')
98+
implementation platform("org.eclipse.xtext:xtext-dev-bom:$xtextVersion")
99+
implementation "org.eclipse.xtext:org.eclipse.xtext.ide:$xtextVersion"
100+
}
101+
```
102+
103+
#### `projectRoot/my.dsl.eclipse.ui/build.gradle`
104+
```groovy
105+
plugins {
106+
id 'com.github.zxhr.xtext-generator-eclipse-plugin'
107+
id 'com.github.zxhr.xtext-generator-eclipse-plugin-test'
108+
}
109+
110+
dependencies {
111+
// ...
112+
}
113+
```
114+
115+
### Modifying the project's generated `plugin.xml`
116+
117+
#### `projectRoot/my.dsl/build.gradle`
118+
```groovy
119+
import groovy.util.XmlSlurper
120+
import groovy.xml.XmlUtil
121+
122+
plugins {
123+
id 'com.github.zxhr.xtext-generator-runtime'
124+
id 'com.github.zxhr.xtext-generator-runtime-test'
125+
}
126+
127+
dependencies {
128+
// ...
129+
}
130+
131+
xtextRuntime {
132+
generateMwe2.configure {
133+
doLast {
134+
def xml = new XmlSlurper().parse(file(pluginXml))
135+
xml.appendNode {
136+
extension(point: 'org.example.extension.point') {
137+
'package'(uri: 'https://www.example.com',
138+
class: 'org.example.cls')
139+
}
140+
}
141+
file(pluginXml).text = XmlUtil.serialize(xml)
142+
}
143+
}
144+
}
145+
```
146+
147+
### Eclipse PDE Configuration
148+
149+
When a project is imported into Eclipse through Buildship, the gradle-xtext-generator plugins will generate
150+
`build/pde/build.properties` and configure the project's `org.eclipse.pde.core.prefs` settings so that
151+
the Xtext DSL projects can be launched within Eclipse PDE from the Plugin-manifest editor.
152+
153+
### Other Notes
154+
155+
* The `com.github.zxhr.xtext-generator-root-project` plugin configures the default `preferXtendStubs` to `false`.
156+
* The plugins will set the project's
157+
[`ext.xtextVersion`](https://docs.gradle.org/current/dsl/org.gradle.api.plugins.ExtraPropertiesExtension.html)
158+
to the xtext version used.
159+
* The plugins include the Xtext-generated MANIFEST.MF into the Gradle
160+
[Jar](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_tasks) task's
161+
[manifest](https://docs.gradle.org/current/javadoc/org/gradle/api/java/archives/Manifest.html);
162+
however, the plugins do not currently handle the logic for merging OSGi headers. For example, if you
163+
want to add another `Export-Package` value to what is generated by Xtext, you will either need to add
164+
it to the manifest generated from Xtext or manually combine it with the `Export-Package` list from the
165+
Xtext using Gradle's Jar manifest.

0 commit comments

Comments
 (0)