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

Fixes.

Browse source
This commit is contained in:
Cedric Beust 2015-10-03 03:25:35 -07:00
parent e8392bb1ea
commit 6d784ca363
1 changed files with 48 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

55
bootstrap/documentation/index.html
View file

@ -72,28 +72,36 @@
<div class="col-md-9"> <div class="col-md-9">
<h2 id="downloading">Downloading and installing Kobalt</h3> <h2 id="downloading">Downloading and installing Kobalt</h3>
<p>
<a href="https://bintray.com/cbeust/generic/kobalt/view">Download the zip file</a> (bottom left of the screen) then unzip it in a location we'll call <code>KOBALT_HOME</code>: <a href="https://bintray.com/cbeust/generic/kobalt/view">Download the zip file</a> (bottom left of the screen) then unzip it in a location we'll call <code>KOBALT_HOME</code>:
</p>
<pre> <pre>
cd $KOBALT_HOME cd $KOBALT_HOME
unzip kobalt-xxx.zip unzip kobalt-xxx.zip
</pre> </pre>
<p>
Change to your project directory and call the <code>kobaltw</code> command with <code>--init</code>: Change to your project directory and call the <code>kobaltw</code> command with <code>--init</code>:
</p>
<pre> <pre>
cd ~/java/project cd ~/java/project
$KOBALT_HOME/kobaltw --init $KOBALT_HOME/kobaltw --init
</pre> </pre>
<p>
This command will do two things: This command will do two things:
</p>
<ol> <ol>
<li>Create a default <code>Build.kt</code> file in your current directory based on what was found there. <li>Create a default <code>Build.kt</code> file in your current directory based on what was found there.
<li>Install the Kobalt Wrapper in your current directory (script `kobaltw`) and in the <code>kobalt/</code> directory. From now on, you can just use <code>./kobaltw</code> to build and you can ignore <code>$KOBALT_HOME</code>. <li>Install the Kobalt Wrapper in your current directory (script `kobaltw`) and in the <code>kobalt/</code> directory. From now on, you can just use <code>./kobaltw</code> to build and you can ignore <code>$KOBALT_HOME</code>.
</ol> </ol>
<p>
You can now attempt to build your project with Kobalt: You can now attempt to build your project with Kobalt:
</p>
<pre> <pre>
./kobaltw assemble ./kobaltw assemble
@ -107,7 +115,9 @@ As of this writing, Kobalt supports Java and Kotlin projects.
<h3 id="general-concepts">General concepts</h3> <h3 id="general-concepts">General concepts</h3>
<p>
The build file is typically called <code>Built.kt</code> and it is a valid Kotlin file. Typically, it contains imports, the declaration of one or more projects and the declaration of additional configurations (e.g. packaging, publishing, etc...). Since it's a Kotlin file, it can also contain any class or function you need: The build file is typically called <code>Built.kt</code> and it is a valid Kotlin file. Typically, it contains imports, the declaration of one or more projects and the declaration of additional configurations (e.g. packaging, publishing, etc...). Since it's a Kotlin file, it can also contain any class or function you need:
</p>
<pre> <pre>
import com.beust.kobalt.* import com.beust.kobalt.*
@ -132,7 +142,9 @@ Here are a few noteworthy details about this small build file:
<h3 id="directives">Directives</h3> <h3 id="directives">Directives</h3>
<p>
Now that we have declared a project, we can use it to configure additional steps of our build, such as the packaging: Now that we have declared a project, we can use it to configure additional steps of our build, such as the packaging:
</p>
<pre> <pre>
import com.beust.kobalt.plugin.packaging.packaging import com.beust.kobalt.plugin.packaging.packaging
@ -145,7 +157,9 @@ val packKobalt = packaging(kobalt) {
} }
</pre> </pre>
<p>
This is the simplest jar declaration you can have. You can trigger the creation of this jar file by invoking the task <code>"assemble"</code>. Note that we passed the <code>kobalt</code> variable to the <code>packaging</code> function, so we make it clear which project we are currently configuring for packaging. The <code>jar</code> directive accepts various settings, so let's be a bit more specific. And let's add a zip file too: This is the simplest jar declaration you can have. You can trigger the creation of this jar file by invoking the task <code>"assemble"</code>. Note that we passed the <code>kobalt</code> variable to the <code>packaging</code> function, so we make it clear which project we are currently configuring for packaging. The <code>jar</code> directive accepts various settings, so let's be a bit more specific. And let's add a zip file too:
</p>
<pre> <pre>
val packKobalt = packaging(kobalt) { val packKobalt = packaging(kobalt) {
@ -165,15 +179,19 @@ val packKobalt = packaging(kobalt) {
} }
</pre> </pre>
<p>
Our jar file is now declared to be a "fat jar" (which means it will include all its dependencies) and we specified a <code>Main-Class</code> to the jar Manifest, which means we will be able to invoke it with <code>java -jar kobalt-0.61.jar</code>. If you don't like this name, you can override it with a <code>name = "myName.jar"</code> statement. Our jar file is now declared to be a "fat jar" (which means it will include all its dependencies) and we specified a <code>Main-Class</code> to the jar Manifest, which means we will be able to invoke it with <code>java -jar kobalt-0.61.jar</code>. If you don't like this name, you can override it with a <code>name = "myName.jar"</code> statement.
</p>
<p> <p>
The zip directive follows a similar structure, although here we are specifying which file we want to include. For more details on the <code>packaging</code> plug-in, please see its documentation. The zip directive follows a similar structure, although here we are specifying which file we want to include. For more details on the <code>packaging</code> plug-in, please see its documentation.
</p>
<h3>Dependencies</h3> <h3>Dependencies</h3>
<p>
You can declare compile and test dependencies as follows: You can declare compile and test dependencies as follows:
</p>
<pre> <pre>
dependencies { dependencies {
@ -188,7 +206,9 @@ dependenciesTest {
<h2 id="maven-repos">Maven repos</h2> <h2 id="maven-repos">Maven repos</h2>
<p>
Kobalt already knows the location of the most popular Maven repos (Maven Central, JCenter, JBoss) but you can add repos with the <code>repos()</code> directive: Kobalt already knows the location of the most popular Maven repos (Maven Central, JCenter, JBoss) but you can add repos with the <code>repos()</code> directive:
</p>
<pre> <pre>
val repos = repos("https://dl.bintray.com/cbeust/maven/") val repos = repos("https://dl.bintray.com/cbeust/maven/")
@ -196,11 +216,13 @@ val repos = repos("https://dl.bintray.com/cbeust/maven/")
<h2 id="using-plug-ins">Using plug-ins</h2> <h2 id="using-plug-ins">Using plug-ins</h2>
<p>
Kobalt comes with a few preconfigured plug-ins but you will want to include external ones as well, which can be downloaded either from a Maven repository (Sonatype, JCenter, ...) or from a local file. Kobalt comes with a few preconfigured plug-ins but you will want to include external ones as well, which can be downloaded either from a Maven repository (Sonatype, JCenter, ...) or from a local file.
</p>
<p> <p>
First of all, let's take a quick look at the tasks available in the default distribution (your actual output might differ somewhat): First of all, let's take a quick look at the tasks available in the default distribution (your actual output might differ somewhat):
</p>
<pre> <pre>
$ ./kobaltw --tasks $ ./kobaltw --tasks
@ -218,14 +240,18 @@ $ ./kobaltw --tasks
assemble Package the artifacts assemble Package the artifacts
</pre> </pre>
<p>
Let's modify our build to include a plug-in. We do this by adding a call to the <code>plugins</code> directive on top of the build file: Let's modify our build to include a plug-in. We do this by adding a call to the <code>plugins</code> directive on top of the build file:
</p>
<pre> <pre>
val repos = repos("https://dl.bintray.com/cbeust/maven/") val repos = repos("https://dl.bintray.com/cbeust/maven/")
val p = plugins("com.beust:kobalt-example-plugin:0.42") val p = plugins("com.beust:kobalt-example-plugin:0.42")
</pre> </pre>
<p>
Now, run the <code>--tasks</code> command again: Now, run the <code>--tasks</code> command again:
</p>
<pre> <pre>
$ ./kobaltw --tasks $ ./kobaltw --tasks
@ -247,11 +273,14 @@ Notice the new <code>"coverage"</code> task, provided by the plug-in <code>kobal
<h2 id="publishing">Publishing</h2> <h2 id="publishing">Publishing</h2>
<p>
Kobalt supports JCenter natively so you can upload your project and make it available on JCenter very easily. Kobalt supports JCenter natively so you can upload your project and make it available on JCenter very easily.
</p>
<p> <p>
First of all, make sure you specified the group, artifactId and version of your project, as required by Maven: First of all, make sure you specified the group, artifactId and version of your project, as required by Maven:
</p>
<pre> <pre>
val kobalt = kotlinProject { val kobalt = kotlinProject {
@ -260,23 +289,26 @@ val kobalt = kotlinProject {
version = "0.72" version = "0.72"
</pre> </pre>
<p>
Next, create a file <code>local.properties</code> in the root directory of your project with the following keys: Next, create a file <code>local.properties</code> in the root directory of your project with the following keys:
</p>
<pre> <pre>
bintray.user=... bintray.user=...
bintray.apikey=... bintray.apikey=...
</pre> </pre>
The values for the <code>user</code> and <code>apikey</code> keys can be found in your bintray profile, as described <a href="https://bintray.com/docs/usermanual/interacting/interacting_editingyouruserprofile.html#anchorAPIKEY">here</a>. Note that you should <b>not</b> check this <code>local.properties</code> file into your source control (so add it to <code>.gitignore</code>).
<p> <p>
The values for the <code>user</code> and <code>apikey</code> keys can be found in your bintray profile, as described <a href="https://bintray.com/docs/usermanual/interacting/interacting_editingyouruserprofile.html#anchorAPIKEY">here</a>. Note that you should <b>not</b> check this <code>local.properties</code> file into your source control (so add it to <code>.gitignore</code>). Next, make sure that your build creates a jar file (using the <code>packaging</code> directive, as explained above).
Make sure that your build creates a jar file (using `packaging`, as explained above). </p>
<p> <p>
Now, all you need to do is to upload your package: Now, all you need to do is to upload your package:
</p>
<pre> <pre>
./gradlew uploadJcenter ./gradlew uploadJcenter
</pre> </pre>
@ -314,12 +346,12 @@ val p = packaging(examplePlugin) {
A plug-in typically has three components: A plug-in typically has three components:
<ul> <ul>
<li>Extending and implementing the methods of `BasePlugin`. <li>Extending and implementing the methods of <code>BasePlugin</code>.
<li>Specifying one or more tasks. <li>Specifying one or more tasks.
<li>Specifying directives (functions that will be used from the build file). <li>Specifying directives (functions that will be used from the build file).
</ul> </ul>
<h3 id="base-plugin"><code>BasePlugin</code></h3> <h3 id="base-plugin">BasePlugin</h3>
The main class of your plugin extends <code>BasePlugin</code> and implements its <code>apply()</code> method and <code>name</code> variable: The main class of your plugin extends <code>BasePlugin</code> and implements its <code>apply()</code> method and <code>name</code> variable:
@ -355,7 +387,9 @@ public fun coverage(project: Project): TaskResult {
<h3 id="plugin-directives">Directives</h3> <h3 id="plugin-directives">Directives</h3>
<p>
Finally, you need to define functions that can be used from the build file (directives). You are encouraged to use the <a href="https://confluence.jetbrains.com/display/Kotlin/Type-safe+Groovy-style+builders">Kotlin DSL approach</a> to expose these functions so that the build file syntax can remain consistent. Typically, these functions will update data that your tasks can then use to do their job. Finally, you need to define functions that can be used from the build file (directives). You are encouraged to use the <a href="https://confluence.jetbrains.com/display/Kotlin/Type-safe+Groovy-style+builders">Kotlin DSL approach</a> to expose these functions so that the build file syntax can remain consistent. Typically, these functions will update data that your tasks can then use to do their job.
</p>
<p> <p>
@ -370,7 +404,9 @@ public fun kotlinProject(init: KotlinProject.() -> Unit): KotlinProject {
} }
</pre> </pre>
<p>
This function returns a <code>KotlinProject</code> and the user can then override variables or invoke methods from this class in their build file: This function returns a <code>KotlinProject</code> and the user can then override variables or invoke methods from this class in their build file:
</p>
<pre> <pre>
val kobalt = kotlinProject { val kobalt = kotlinProject {
@ -379,7 +415,10 @@ val kobalt = kotlinProject {
... ...
</pre> </pre>
<p>
Using an extension function to define a directive allows you to add new functions to Kobalt classes. For example, currently, a project can have <code>"dependencies"</code> and <code>"dependenciesTest"</code>. For a coverage plug-in, we would want to add a <code>"dependenciesCoverage"</code> section, which can be easily done by defining an extension function on <code>Project</code>: Using an extension function to define a directive allows you to add new functions to Kobalt classes. For example, currently, a project can have <code>"dependencies"</code> and <code>"dependenciesTest"</code>. For a coverage plug-in, we would want to add a <code>"dependenciesCoverage"</code> section, which can be easily done by defining an extension function on <code>Project</code>:
</p>
<pre> <pre>
@Directive @Directive
@ -390,7 +429,9 @@ public fun Project.dependenciesCoverage(ini: Dependencies.() -> Unit) : Dependen
} }
</pre> </pre>
<p>
And we can now use: And we can now use:
</p>
<pre> <pre>
val p = kotlinProject { val p = kotlinProject {