erik/kobalt-doc
erik/kobalt-doc
1
0
Fork 0
mirror of https://github.com/ethauvin/kobalt-doc.git synced 2025-04-25 20:07:11 -07:00
Code Releases Activity

Hyperlinks.

Browse source
This commit is contained in:
Cedric Beust 2015-11-30 21:38:18 -08:00
parent 57882c967f
commit a6aeee1236
1 changed files with 38 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

70
plug-in-development/index.html
View file

@ -94,7 +94,7 @@
</ul> </ul>
<p> <p>
All plug-in actors are interfaces that extend <code>IPluginActor</code>. Plug-ins extend <code>IPlugin</code>, All plug-in actors are interfaces that extend <code>IPluginActor</code>. Plug-ins extend <code>IPlugin</code>,
interceptors extend <code>IInterceptor</code> and contributors extend <code>IContributor</code>. When Kobalt parses your interceptors extend <code><code>IInterceptor</code></code> and contributors extend <code><code>IContributor</code></code>. When Kobalt parses your
<code>kobalt-plugin.xml</code>, it instantiates all the classes found in the <code>&lt;plugin-actors&gt;</code> tag <code>kobalt-plugin.xml</code>, it instantiates all the classes found in the <code>&lt;plugin-actors&gt;</code> tag
and then introspects them to find out which <code>IPluginActor</code> interfaces that class implements. and then introspects them to find out which <code>IPluginActor</code> interfaces that class implements.
@ -130,52 +130,54 @@
<td>Description</td> <td>Description</td>
</thead> </thead>
<tr> <tr>
<td><code>IBuildDirectoryInterceptor</code></td> <td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IBuildDirectoryInterceptor.kt">IBuildDirectoryInterceptor</a></code></td>
<td><code>IInterceptor</code></td> <td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code><code>IInterceptor</code></code></a> </td>
<td> <td>
Plug-ins that need to generate class files in a different directory than the default one should Plug-ins that need to generate class files in a different directory than the default one should
implement this interface. implement this interface.
</td> </td>
</tr> </tr>
<tr> <tr>
<td><code>IClasspathContributor</code></td> <td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IClasspathContributor.kt">IClasspathContributor
<td><code>IContributor</code></td> </a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code><code>IContributor</code></code></a> </td>
<td> Classpath contributors let you specify additional jar files or directories that will be used by <td> Classpath contributors let you specify additional jar files or directories that will be used by
the <code>"compile"</code> task. the <code>"compile"</code> task.
</td> </td>
</tr> </tr>
<tr> <tr>
<td><code>IClasspathInterceptor</code></td> <td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IClasspathInterceptor.kt">IClasspathInterceptor
<td><code>IInterceptor</code></td> </a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IInterceptor</code></a> </td>
<td> <td>
Plug-ins that want to modify the classpath before Kobalt uses it should implement this interface. Plug-ins that want to modify the classpath before Kobalt uses it should implement this interface.
</td> </td>
</tr> </tr>
<tr> <tr>
<td><code>ICompilerContributor</code></td> <td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/ICompilerContributor.kt">ICompilerContributor</a></code></td>
<td><code>IContributor</code></td> <td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td> <td>
Plug-ins that know how to turn files into bytecodes should implement this interface. Plug-ins that know how to turn files into bytecodes should implement this interface.
</td> </td>
</tr> </tr>
<tr> <tr>
<td><code>ICompilerInterceptor</code></td> <td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/ICompilerInterceptor.kt">ICompilerInterceptor</a></code></td>
<td><code>IInterceptor</code></td> <td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IInterceptor</code></a> </td>
<td> <td>
Plug-ins that implement this interface get a chance to alter the dependencies of a project (<code>dependencies{}</code>, <code>dependenciesTest{}</code>, ...) before Kobalt sees them. Plug-ins that implement this interface get a chance to alter the dependencies of a project (<code>dependencies{}</code>, <code>dependenciesTest{}</code>, ...) before Kobalt sees them.
</td> </td>
</tr> </tr>
<tr> <tr>
<td><code>IDocContributor</code></td> <td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IDocContributor.kt">IDocContributor</a></code></td>
<td><code>IContributor</code></td> <td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td> <td>
Plug-ins that know how to generate documentation out of source files should implement this interface. Plug-ins that know how to generate documentation out of source files should implement this interface.
</td> </td>
</tr> </tr>
<tr> <tr>
<td><code>IInitContributor</code></td> <td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IInitContributor.kt">IInitContributor</a></code></td>
<td><code>IContributor</code></td> <td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td>Kobalt supports the <code>--init</code> command line parameter, which generates a default build file <td>Kobalt supports the <code>--init</code> command line parameter, which generates a default build file
based on the files found in the current directory. Any plug-in that wants to be part of this process need based on the files found in the current directory. Any plug-in that wants to be part of this process need
to implement this interface. In this case, both the Java and Kotlin plug-ins define such a contributor to implement this interface. In this case, both the Java and Kotlin plug-ins define such a contributor
@ -183,15 +185,15 @@
</td> </td>
</tr> </tr>
<tr> <tr>
<td><code>IProjectContributor</code></td> <td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IProjectContributor.kt">IProjectContributor</a></code></td>
<td><code>IContributor</code></td> <td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td>Some plug-ins produce projects (Java, Kotlin) while others don't (Packaging, Application, etc...). The ones that <td>Some plug-ins produce projects (Java, Kotlin) while others don't (Packaging, Application, etc...). The ones that
do need to register themselves as project contributors. This is how Kobalt collects all the projects defined do need to register themselves as project contributors. This is how Kobalt collects all the projects defined
after a build file was parsed.</td> after a build file was parsed.</td>
</tr> </tr>
<tr> <tr>
<td><code>IRepoContributor</code></td> <td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IRepoContributor.kt">IRepoContributor</a></code></td>
<td><code>IContributor</code></td> <td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td> <td>
Some plug-ins might want to add their own repository to the list of repositories that Kobalt already supports. Some plug-ins might want to add their own repository to the list of repositories that Kobalt already supports.
This is the case of the Android plug-in which, once the <code>ANDROID_HOME</code> environment variable has been This is the case of the Android plug-in which, once the <code>ANDROID_HOME</code> environment variable has been
@ -200,22 +202,24 @@
</td> </td>
</tr> </tr>
<tr> <tr>
<td><code>ISourceDirectoryInterceptor</code></td> <td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/ISourceDirectoriesInterceptor.kt">
<td><code>IInterceptor</code></td> ISourceDirectoriesInterceptor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code><code>IInterceptor</code></code></a> </td>
<td> <td>
Plug-ins that wamt to add, remove or alter the source directories should implement this interface. Plug-ins that wamt to add, remove or alter the source directories should implement this interface.
</td> </td>
</tr> </tr>
<tr> <tr>
<td><code>IRunnerContributor</code></td> <td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IRunnerContributor.kt">IRunnerContributor</a></code></td>
<td><code>IContributor</code></td> <td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td> <td>
Plug-ins that can operate when the <code>"run"</code> task gets invoked should implement that interface. Plug-ins that can operate when the <code>"run"</code> task gets invoked should implement that interface.
</td> </td>
</tr> </tr>
<tr> <tr>
<td><code>ITestRunnerContributor</code></td> <td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/ITestRunnerContributor.kt">
<td><code>IContributor</code></td> ITestRunnerContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td> <td>
Plug-ins that can operate when the <code>"test"</code> task gets invoked should implement that interface. Plug-ins that can operate when the <code>"test"</code> task gets invoked should implement that interface.
</td> </td>
@ -256,7 +260,8 @@ class JavaBuildGenerator: IInitContributor {</pre>
<p> <p>
Several plug-ins might want to contribute to a specific task where only one participant only should be allowed, Several plug-ins might want to contribute to a specific task where only one participant only should be allowed,
such as running tests or generating documentation. Even the simple task of compiling should probably only such as running tests or generating documentation. Even the simple task of compiling should probably only
ever be performed by no more than one plug-in. Therefore, when comes the time to compile a project, ever be performed by no more than one plug-in for a given project. Therefore, when comes the time to
compile a project,
Kobalt needs to find which plug-in is the most suitable for that task and pick it. In order to do that, Kobalt needs to find which plug-in is the most suitable for that task and pick it. In order to do that,
plug-ins that contribute to tasks that can only be performed by one candidate need to declare their plug-ins that contribute to tasks that can only be performed by one candidate need to declare their
<em>affinity</em> to that task for a given project. <em>affinity</em> to that task for a given project.
@ -266,14 +271,15 @@ class JavaBuildGenerator: IInitContributor {</pre>
</p> </p>
<pre> <pre>
interface IAffinity { interface IAffinity {
/** /**
* @return an integer indicating the affinity of your actor for the given project. The actor that returns * @return an integer indicating the affinity of your actor for the given project.
* the highest affinity gets selected. * The actor that returns the highest affinity gets selected.
*/ */
fun affinity(project: Project, context: KobaltContext) : Int</pre> fun affinity(project: Project, context: KobaltContext) : Int
}</pre>
<p> <p>
For example, the JavaPlugin implements the <code>ICompilerContributor</code> interface and then overrides For example, the JavaPlugin implements the <code>ICompilerContributor</code> interface and then overrides
the <code>affinity</code> method to make sure it gets run for Java projects but ignored for others: the <code>affinity()</code> method to make sure it gets run for Java projects but ignored for others:
</p> </p>
<pre> <pre>
override fun affinity(project: Project, context: KobaltContext) = override fun affinity(project: Project, context: KobaltContext) =