Update build instructions in ReadMe to include gradle build step.

Also update links and overall readme structure.
This commit is contained in:
Ilya Gorbunov
2017-04-07 03:48:57 +03:00
parent f5647fb27f
commit 5aabcb6ea3
7 changed files with 96 additions and 79 deletions

View File

@@ -45,65 +45,49 @@ To build this project, first time you try to build you need to run this:
which will setup the dependencies on
* intellij-core: is a part of command line compiler and contains only necessary APIs.
* idea-full: is a full blown IntelliJ IDEA Community Edition to be used in former plugin module.
* `intellij-core` is a part of command line compiler and contains only necessary APIs.
* `idea-full` is a full blown IntelliJ IDEA Community Edition to be used in the plugin module.
Then, you need to run
ant -f build.xml
which will build the binaries of the compiler and put them into the 'dist' directory. You may need to increase the **heap size** for Ant using
which will build the binaries of the compiler and put them into the `dist` directory. You may need to increase the **heap size** for Ant using
[ANT_OPTS](https://web.liferay.com/community/wiki/-/wiki/Main/Ant+opts).
**OPTIONAL:** Maven distribution is built separately, run
**OPTIONAL:** Maven artifact distribution is built separately, go into `libraries` directory after building the compiler and run:
mvn package
./gradlew build install
mvn install
from 'libraries' directory after building the compiler. Refer to [libraries/ReadMe.md](libraries/ReadMe.md) for details.
> Note: on Windows type `gradlew` without the leading `./`
Refer to [libraries/ReadMe.md](libraries/ReadMe.md) for details.
## Working with the project in IntelliJ IDEA
The [root kotlin project](https://github.com/JetBrains/kotlin) already has an IntelliJ IDEA project, you can just open it in IntelliJ IDEA.
You may need to set the Project SDK (File -> Project Structure -> Project).
You may also need to add `tools.jar` to your SDK: File -> Project Structure -> SDKs -> <Your JDK> -> Classpath,
You may need to set the Project SDK (`File -> Project Structure -> Project`).
You may also need to add `tools.jar` to your SDK:
File -> Project Structure -> SDKs -> <Your JDK> -> Classpath
then choose the `tools.jar` in the JDK's `lib` directory.
If you are not dealing with Android, you may need to disable the Android Plugin in order to compile the project.
### <a name="installing-plugin"></a> Installing the latest Kotlin plugin
Since Kotlin project contains code written in Kotlin itself, you will also need a Kotlin plugin to build the project in IntelliJ IDEA.
To keep the plugin version in sync with the rest of the team and our [Continuous Integration server](https://teamcity.jetbrains.com/project.html?projectId=Kotlin&tab=projectOverview)
you should install the according to the [instructions below](#plugin-for-contributors).
If you want to have an IntelliJ IDEA installation without the Kotlin plugin which is separate to your default IntelliJ IDEA installation which has the Kotlin
plugin [see this document](https://devnet.jetbrains.com/docs/DOC-181) which describes how to have multiple IntelliJ IDEA installations using different configurations and plugin directories.
From this root project there are Run/Debug Configurations for running IDEA or the Compiler Tests for example; so if you want to try out the latest and greatest IDEA plugin
* VCS -> Git -> Pull
* Run IntelliJ IDEA
* a child IntelliJ IDEA with the Kotlin plugin will then startup
* you can now open the [kotlin libraries project](https://github.com/JetBrains/kotlin/tree/master/libraries) to then work with the various kotlin libraries etc.
### <a name="pre-built-plugin"></a>Using a pre-built Kotlin IntelliJ IDEA plugin
There are several options for getting Kotlin plugin. A stable version can be obtained as any other plugin for IntelliJ IDEA:
Preferences -> Plugins -> Install JetBrains plugin... -> Search with "Kotlin" string
The most recent version of the plugin can be downloaded from the
[IDEA Plugin and Tests CI build](https://teamcity.jetbrains.com/project.html?projectId=project67&tab=projectOverview). When downloading is
finished you can install it with "Install plugin from disk...":
Preferences -> Plugins -> Install plugin from disk...
You can now open any Kotlin based projects.
<a name="plugin-for-contributors"></a>
**Note for contributors**: If you are planning to contribute to Kotlin project you probably want to have locally the same version of plugin that build server is using for building.
You probably want to have locally the same version of plugin that build server is using for building.
As this version is constantly moving, the best way to always be updated is to let IntelliJ IDEA notify you when it is time to renew your plugin.
Open
To keep the plugin version in sync with the rest of the team and our [Continuous Integration server](https://teamcity.jetbrains.com/project.html?projectId=Kotlin&tab=projectOverview)
you should setup IDEA to update the plugin directly from the build server.
Open:
Preferences -> Plugins -> Browse Repositories -> Manage Repositories...
@@ -113,10 +97,22 @@ and add the following URL to your repositories:
Then update the list of plugins in "Browse Repositories", you'll see two versions of Kotlin there, install the one with the higher version number.
If you want to keep an IntelliJ IDEA installation with that bleeding edge Kotlin plugin for working Kotlin project sources only separate to your default IntelliJ IDEA installation with the stable Kotlin
plugin [see this document](https://intellij-support.jetbrains.com/hc/en-us/articles/207240985-Changing-IDE-default-directories-used-for-config-plugins-and-caches-storage), which describes how to have multiple IntelliJ IDEA installations using different configurations and plugin directories.
### Compiling and running
From this root project there are Run/Debug Configurations for running IDEA or the Compiler Tests for example; so if you want to try out the latest and greatest IDEA plugin
* VCS -> Git -> Pull
* Run IntelliJ IDEA
* a child IntelliJ IDEA with the Kotlin plugin will then startup
* you can now open the [kotlin libraries project](https://github.com/JetBrains/kotlin/tree/master/libraries) to then work with the various kotlin libraries etc.
# Contributing
We love contributions! There's [lots to do on Kotlin](https://youtrack.jetbrains.com/issues/KT) and on the
[standard library](https://youtrack.jetbrains.com/issues/KT?q=Subtask+of%3A+KT-2554+%23Unresolved) so why not chat with us
[standard library](https://youtrack.jetbrains.com/issues/KT?q=%23Kotlin%20%23Unresolved%20and%20(links:%20KT-2554,%20KT-4089%20or%20%23Libraries)) so why not chat with us
about what you're interested in doing? Please join the #kontributors channel in [our Slack chat](http://kotlinslackin.herokuapp.com/)
and let us know about your plans.
@@ -128,8 +124,8 @@ A nice gentle way to contribute would be to review the [standard library docs](h
and find classes or functions which are not documented very well and submit a patch.
In particular it'd be great if all functions included a nice example of how to use it such as for the
[`hashMapOf()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/hash-map-of.html) function.
This is implemented using the [`@sample`](https://github.com/JetBrains/kotlin/blob/master/libraries/stdlib/src/kotlin/collections/Maps.kt#L64)
[`hashMapOf()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/hash-map-of.html) function.
This is implemented using the [`@sample`](https://github.com/JetBrains/kotlin/blob/1.1.0/libraries/stdlib/src/kotlin/collections/Maps.kt#L91)
macro to include code from a test function. The benefits of this approach are twofold; First, the API's documentation is improved via beneficial examples that help new users and second, the code coverage is increased.
Also the [JavaScript translation](https://github.com/JetBrains/kotlin/blob/master/js/ReadMe.md) could really use your help. See the [JavaScript contribution section](https://github.com/JetBrains/kotlin/blob/master/js/ReadMe.md) for more details.
@@ -139,8 +135,8 @@ Also the [JavaScript translation](https://github.com/JetBrains/kotlin/blob/maste
The Kotlin compiler is written in Java and Kotlin (we gradually migrate more and more of it to pure Kotlin). So the easiest way to work on the compiler or IntelliJ IDEA plugin is
* download a clean [IDEA 15 EAP build](https://confluence.jetbrains.com/display/IDEADEV/IDEA+15+EAP)
* [install the Kotlin plugin](#pre-built-plugin)
* download a recent [IntelliJ IDEA](https://www.jetbrains.com/idea/?fromMenu#chooseYourEdition), Community edition is enough
* [install the Kotlin plugin](#installing-plugin)
* open the [root kotlin project](https://github.com/JetBrains/kotlin) in IDEA (opening the kotlin directory)
You can now run the various Run/Debug Configurations such as
@@ -152,16 +148,19 @@ You can now run the various Run/Debug Configurations such as
## If you want to work on the Kotlin libraries
* download a clean [IDEA 15 EAP build](https://confluence.jetbrains.com/display/IDEADEV/IDEA+15+EAP)
* [install the Kotlin plugin](#pre-built-plugin)
* download a recent [IntelliJ IDEA](https://www.jetbrains.com/idea/?fromMenu#chooseYourEdition), Community edition is enough
* [install the Kotlin plugin](#installing-plugin)
* open the [kotlin libraries project](https://github.com/JetBrains/kotlin/tree/master/libraries)
Then build via
cd libraries
./gradlew build install
mvn install
> Note: on Windows type `gradlew` without the leading `./`
Some of the code in the standard library is created by generating code from templates. See the [README](https://github.com/JetBrains/kotlin/blob/master/libraries/stdlib/ReadMe.md) in the stdlib section for how run the code generator. The existing templates can be used as examples for creating new ones.
Some of the code in the standard library is created by generating code from templates. See the [README](libraries/stdlib/ReadMe.md) in the stdlib section for how run the code generator. The existing templates can be used as examples for creating new ones.
## Submitting patches

View File

@@ -4,26 +4,24 @@ This module performs the translation of Kotlin source code to JavaScript.
There are various Kotlin APIs to JavaScript environments and libraries in the [js.libraries](https://github.com/JetBrains/kotlin/tree/master/js/js.libraries/src) project.
## Compiling the standard Kotlin library to JavaScript
## Compiling the Kotlin Standard Library for JavaScript
The Kotlin Standard Library for JS is built with gradle, see the corresponding module's [ReadMe](../libraries/stdlib/js/ReadMe.md).
* the [kotlin-js-library](https://github.com/JetBrains/kotlin/tree/master/libraries/tools/kotlin-js-library) module creates a jar containing all the Kotlin source code for the runtime and standard kotlin library code (both definitions and implementation code) to be compiled to JavaScript.
* the [kotlin-js-tests](https://github.com/JetBrains/kotlin/tree/master/libraries/tools/kotlin-js-tests) module then compiles a selection of test cases from the [Kotlin standard library for the JVM](https://github.com/JetBrains/kotlin/tree/master/libraries/stdlib) to JavaScript. These tests can then be [run in a web browser using QUnit](https://github.com/JetBrains/kotlin/blob/master/libraries/tools/kotlin-js-tests/ReadMe.md)
* the [kotlin-js-tests-junit](https://github.com/JetBrains/kotlin/tree/master/libraries/tools/kotlin-js-tests-junit) then [runs the JavaScript tests for the standard library inside JUnit](https://github.com/JetBrains/kotlin/blob/master/libraries/tools/kotlin-js-tests-junit/ReadMe.md) using Selenium and the underlying JavaScript & QUnit so that the JavaScript can be tested as part of the maven continuous integration build.
## Reusing JVM based test cases in JavaScript
Any Kotlin test cases using the **org.junit.Test** annotation and the [kotlin.test](http://jetbrains.github.com/kotlin/versions/snapshot/apidocs/kotlin/test/package-summary.html) package, such as [this test case](https://github.com/JetBrains/kotlin/blob/master/libraries/stdlib/test/StringTest.kt#L5) are automatically converted to JavaScript using [QUnit](http://qunitjs.com/).
Any Kotlin test cases using the **org.junit.Test** annotation and the [kotlin.test](../libraries/kotlin.test) package, such as [this test case](../libraries/stdlib/test/text/StringNumberConversionTest.kt#L16) are automatically converted to JavaScript using [QUnit](http://qunitjs.com/).
This allows the test cases to be [ran directly in a web page in any web browser](https://github.com/JetBrains/kotlin/blob/master/libraries/tools/kotlin-js-tests/ReadMe.md).
This allows the test cases to be [run directly in a web page in any web browser](../libraries/stdlib/js/ReadMe.md).
## Using the Kotlin Library in JavaScript
There is a [simple sample](https://github.com/JetBrains/kotlin/blob/master/libraries/examples/browser-example/ReadMe.md) which shows how to use the [Kotlin Standard Library](http://jetbrains.github.com/kotlin/versions/snapshot/apidocs/index.html) from inside JavaScript in a web page or in a JVM using [kool.io](http://kool.io/)'s [JavaFX browser](https://github.com/koolio/kool/blob/master/samples/kool-template-sample/ReadMe.md)
There is a [simple sample](../libraries/examples/browser-example/ReadMe.md) which shows how to use the [Kotlin Standard Library](https://kotlinlang.org/api/latest/jvm/stdlib/index.html) from inside JavaScript in a web page.
## Contributing
We love contributions! The JavaScript translation could really use your help! If you fancy contributing:
* check the [contributing section](https://github.com/JetBrains/kotlin/blob/master/ReadMe.md) on general stuff like getting the code etc
* here's the list of [current excluded standard library unit tests](https://github.com/JetBrains/kotlin/blob/master/libraries/tools/kotlin-js-tests/pom.xml#L46) from the JavaScript JUnit test run; see if you can fix one of those? (Check the TODO commands and the links to specific issues)
* try fix one of the pending [JavaScript translation issues](https://youtrack.jetbrains.com/issues/KT?q=Subsystems:%20%7BBack-end.%20JavaScript%7D%20-Resolved)

View File

@@ -1,10 +1,14 @@
## Kotlin Libraries
This area of the project is all written in Kotlin and assumes you've got the [Kotlin IDEA plugin installed](http://confluence.jetbrains.net/display/Kotlin/Getting+Started).
This area of the project is all written in Kotlin and assumes you've got the [Kotlin IDEA plugin installed](../ReadMe.md#installing-plugin).
This area of the project uses Maven for its build. You need to install a recent [Maven](http://maven.apache.org/) distribution and
setup environment variables as following:
This area of the project uses Gradle and Maven for its build. When you open this project directory in IDEA the first time, it suggests you to import both gradle and maven projects. After importing you'll be able to explore and run gradle tasks and maven goals directly from IDEA with the instruments on the right sidebar.
### Building
You need to install a recent [Maven](http://maven.apache.org/) distribution and setup environment variables as following:
JAVA_HOME="path to JDK 1.8"
JDK_16="path to JDK 1.6"
JDK_17="path to JDK 1.7"
JDK_18="path to JDK 1.8"
@@ -13,15 +17,21 @@ The main part of the Kotlin standard library, `kotlin-stdlib`, is compiled again
for the standard library, `kotlin-stdlib-jre7` and `kotlin-stdlib-jre8`, which are compiled against JDK 1.7 and 1.8 respectively,
so you need to have all these JDKs installed.
Then you'll be able to build tools and libraries with:
Be sure to build Kotlin compiler distribution before launching Gradle and Maven: see [root ReadMe.md, section "Building"](../ReadMe.md#installing-plugin).
Core libraries are built with gradle, you can run that build using the gradle wrapper script even without local gradle installation:
./gradlew build install
> Note: on Windows type `gradlew` without the leading `./`
This command executes the `build` task, which assembles the artifacts and run the tests, and the `install` task, which puts the artifacts to the local maven repository to be used by the subsequent maven build.
The rest of tools and libraries are built with maven:
mvn install
For more details see the [Getting Started Guide](http://confluence.jetbrains.net/display/Kotlin/Getting+Started).
Be sure to build Kotlin compiler distribution before launching Maven: see ReadMe.md at root level, section "Building".
If your maven build is failing with Out-Of-Memory errors, set JVM options for maven in MAVEN_OPTS environment variable like this:
If your maven build is failing with Out-Of-Memory errors, set JVM options for maven in `MAVEN_OPTS` environment variable like this:
MAVEN_OPTS="-Xmx2G"
@@ -32,7 +42,7 @@ Gradle plugin sources can be found at the [kotlin-gradle-plugin](tools/kotlin-gr
To build only gradle plugin and necessary dependencies use the following command:
```bash
mvn clean install -pl :kotlin-gradle-plugin -am
# to skip all tests also add -DskipTests
# to skip all tests also add -DskipTests -PnoTest
```
### Gradle integration tests
@@ -41,7 +51,7 @@ Gradle integration tests can be found at the [kotlin-gradle-plugin-integration-t
These tests are slow, so they are *skipped by default*.
To run integration tests use the 'run-gradle-integration-tests' profile:
To run integration tests use the `run-gradle-integration-tests` profile:
```bash
mvn clean install -pl :kotlin-gradle-plugin-integration-tests -am -Prun-gradle-integration-tests
```

View File

@@ -1,14 +1,17 @@
## The Kotlin Standard Library
This module creates the [standard library for kotlin](http://jetbrains.github.com/kotlin/versions/snapshot/apidocs/index.html).
This module creates the [standard library for kotlin](http://kotlinlang.org/api/latest/jvm/stdlib/index.html).
### Notes for contributors
We use some code generation to apply the various collection-like methods to various different types like arrays, strings, kotlin.Iterable and java.lang.Iterable etc.
We use some code generation to generate the various utility extension function for the various collection-like types like arrays, strings, `Collection<T>`, `Sequence<T>`, `Map<K, V>` etc.
To run the code generator from a kotlin checkout
These sources are placed into `generated` folder and their names are prefixed with the underscore, for example `generated/_Collections.kt`
cd libraries/tools/kotlin-stdlib-gen
mvn compile exec:java
To run the code generator from the `libraries` directory of a kotlin checkout, use the following command:
This then runs the [GenerateStandardLib.kt](https://github.com/JetBrains/kotlin/blob/master/libraries/tools/kotlin-stdlib-gen/src/generators/GenerateStandardLib.kt) script to create the source from the files for java.lang.Iterable<T> and java.util.Collection etc.
./gradlew :tools:kotlin-stdlib-gen:run
> Note: on Windows type `gradlew` without the leading `./`
This then runs the script which generates a significant part of stdlib sources from the [templates](https://github.com/JetBrains/kotlin/tree/master/libraries/tools/kotlin-stdlib-gen/src/templates) authored with a special kotlin based DSL.

View File

@@ -1,5 +1,9 @@
## Kotlin Standard Library for JS
This module produces a `kotlin-stdlib-js` jar which contains all the Kotlin source code for the runtime and standard kotlin library code (both definitions and implementation code) compiled to JavaScript.
The tests of this module can be run and debugged inside any browser by opening the **web/index.html** file in this directory to run the test cases using [Qunit](http://qunitjs.com/).
You should execute `:karmaDependencies` gradle task before running these tests to fetch the required Qunit dependency.
You should execute `karmaDependencies` gradle task before running these tests to fetch the required Qunit dependency.
These tests are also run during CI build with [gradle karma plugin](https://github.com/craigburke/karma-gradle) in PhantomJS browser.

View File

@@ -6,11 +6,13 @@ and ensure that the public binary API wasn't changed in a way that make this cha
## How to run
Compile and run tests. `CasesPublicAPITest` verifies the tool itself,
and `RuntimePublicAPITest` dumps the public API of `kotlin-runtime` and `kotlin-stdlib` jars,
which must be built beforehand with maven.
and `RuntimePublicAPITest` dumps the public API of `kotlin-stdlib`,
`kotlin-stdlib-jre7/8` and `kotlin-reflect` jars,
which must be built beforehand with gradle. Use `clean assemble` tasks,
since the incremental compilation currently doesn't produce all the required output.
When substantial changes are made to the public API, it may be convenient to overwrite
the entire dump and compare changes later before commiting: pass `-Doverwrite.output=true`
the entire dump and compare changes later before committing: pass `-Doverwrite.output=true`
property to the test to do so.
Also you can use shared run configuration "Binary compatibility tests", which also

View File

@@ -1,11 +1,12 @@
## Code Generation for Standard Library
Some of the code in the standard library is created by code generation based on templates.
For example, many Array methods need to be implemented separately for Array<T>, ByteArray, ShortArray, IntArray, etc.
For example, many `Array` methods need to be implemented separately for `Array<T>`, `ByteArray`, `ShortArray`, `IntArray`, etc.
To run the code generator from a kotlin checkout
To run the code generator from the `libraries` directory of a kotlin checkout, use the following command:
cd libraries/tools/kotlin-stdlib-gen
mvn compile exec:java
./gradlew :tools:kotlin-stdlib-gen:run
This then runs the [GenerateStandardLib.kt](https://github.com/JetBrains/kotlin/blob/master/libraries/tools/kotlin-stdlib-gen/src/generators/GenerateStandardLib.kt) script to create the source from the files for java.lang.Iterable<T> and java.util.Collection etc.
> Note: on Windows type `gradlew` without the leading `./`
This then runs the script which generates a significant part of stdlib sources from the [templates](https://github.com/JetBrains/kotlin/tree/master/libraries/tools/kotlin-stdlib-gen/src/templates) authored with a special kotlin based DSL.