diff --git a/documentation/index.html b/documentation/index.html index 277afae..95c4696 100644 --- a/documentation/index.html +++ b/documentation/index.html @@ -265,7 +265,76 @@ dependencies { -

Maven repos

+

Templates

+

+ Templates are invoked with the --init parameter and typically used when you are creating + a new project and you want Kobalt to generate a few files to get you started. Plug-ins can provide multiple + templates and you can invoke as many as you need to get your project started. You can get a list of available + templates with the --listTemplates parameter: +

+
+$ kobaltw --listTemplates
+Available templates
+  Plug-in: Kobalt
+    "java"              Generates a simple Java project
+    "kotlin"            Generates a simple Kotlin project
+    "kobalt-plugin"     Generate a sample Kobalt plug-in project
+

+ You can then invoke any of these templates with --init: + 

+$ kobaltw --init kobalt-plugin
+Build this project with `./kobaltw assemble`
+

+ Kobalt just generated a full project that will create a simple Kobalt plug-in. This plug-in adds + a simple task to Kobalt, so let's build it and test it: +

+ 
+$ ./kobaltw assemble
+----- kobalt-line-count:compile
+----- kobalt-line-count:assemble
+Created .\kobaltBuild\libs\kobalt-line-count-0.18.jar
+Created .\kobaltBuild\libs\kobalt-line-count-0.18-sources.jar
+Created .\kobaltBuild\libs\kobalt-line-count-0.18-javadoc.jar
+Wrote .\kobaltBuild\libs\kobalt-line-count-0.18.pom
+BUILD SUCCESSFUL (5 seconds)
+

+ We can test this plug-in with another useful command line parameter: --pluginJarFiles. You give this parameter a comma-separated list of jar files, each of which is expected to be a Kobalt plug-in. Let's invoke + Kobalt with it and ask for a list of available tasks (some of the output was elided): +

+
+$ ./kobaltw --pluginJarFiles kobaltBuild/libs/kobalt-line-count-0.18.jar --tasks
+...
+  ===== kobalt-line-count =====
+    dynamicTask         Dynamic task
+    lineCount           Count the lines
+...
+
+

+ Kobalt loaded this plug-in and added the tasks that it provides. The parameter + --pluginJarFiles is mostly targeted at Kobalt plug-in developers so you can test + your plug-ins on your local file system without having to upload them to a Maven repo. More commonly, + you will run templates from plug-ins published in a Maven repository, and for this, + you use the --plugins parameter. For example, let's see what templates the + Android Kobalt plug-in offers: +

+ 
+$ ./kobaltw --plugins com.beust:kobalt-android: --listTemplates
+Available templates
+  Plug-in: Kobalt
+    "java"              Generates a simple Java project
+    "kotlin"            Generates a simple Kotlin project
+    "kobalt-plugin"             Generate a sample Kobalt plug-in project
+  Plug-in: Android
+    "android-java"              Generate a simple Android Java project
+

+ We see the same plug-ins we just reviewed and a new one provided by the Android plug-in called + "android-java". The --plugins parameter expects a comma-separated list of plug-in + id's and it acts as if you had specified these Maven id's in your Build.kt file. + The reason why this parameter is useful is that typically, when you run a template, you don't + have a build file yet since you are starting a project from scratch. +

+ +

Maven repos

Unauthenticated repos

Kobalt already knows the location of the most popular Maven repos (Maven Central, JCenter, JBoss) but you can add repos with the repos() directive: @@ -453,10 +522,17 @@ New versions found: --init - Comma-separated strings + Comma-separated strings of template names. null - Initialize a project for Kobalt with the given archetypes. - The parameter to this argument is a list of archetype names separated by commas, e.g. "java,myProject". Each archetype will be invoked in order so they can generate their files. + Initialize a project for Kobalt with the given templates. + The parameter to this argument is a list of template names separated by commas, e.g. "java,myProject". Each template will be invoked in order so they can generate their files. + + + --listTemplates + + N/A + List all the templates available. + Templates displayed by this command can then be passed as an argument to the --init parameter. --log @@ -472,6 +548,13 @@ New versions found: Display information about the given id. Display which repo this artifact can be found in and the whole graph of its dependencies. + + --resolve + Maven id
(e.g. "com.beust:kobalt:0.228") + N/A + Display information about the given id. + Display which repo this artifact can be found in and the whole graph of its dependencies. + --tasks Boolean diff --git a/plug-in-development/index.html b/plug-in-development/index.html index c48bfbf..9a89bcb 100644 --- a/plug-in-development/index.html +++ b/plug-in-development/index.html @@ -109,9 +109,9 @@ class JavaPlugin : ICompilerContributor, IDocContributor { With this declaration, we know that the JavaPlugin contributes a compiler and a doc generator. 

-class JavaBuildGenerator: IInitContributor {
+class JavaBuildGenerator: ITemplateContributor {

- This class is declaring that it wants to take part in the --init process (i.e. it can generate an archetype), discussed below. + This class is declaring that it wants to take part in the --init process (i.e. it can generate a template), discussed below.

List of plug-in actors

@@ -184,16 +184,6 @@ class JavaBuildGenerator: IInitContributor { Plug-ins that know how to generate documentation out of source files should implement this interface. - - IInitContributor - IContributor - When invoked with --init followed by archetype names separated by commas, - Kobalt will invoke each of these contributors so they can generate their files. - Archetypes are useful to create projects from scratch with a minimal number of - files to get started. For example, the "java" archetype will generate a `Build.kt` - file suitable for a brand new Java project. - - IProjectContributor IContributor @@ -236,6 +226,16 @@ class JavaBuildGenerator: IInitContributor { Plug-ins that want to add, remove or alter the source directories should implement this interface. + + ITemplateContributor + IContributor + When invoked with --init followed by template names separated by commas, + Kobalt will invoke each of these contributors so they can generate their files. + Templates are useful to create projects from scratch with a minimal number of + files to get started. For example, the "java" template will generate a Build.kt + file suitable for a brand new Java project. + + ITestRunnerContributor