Skip to content

Commit a68d69e

Browse files
dancer1325dancer1325
committed
doc(): clear notes and add examples
1 parent db6d850 commit a68d69e

File tree

4 files changed

+149
-101
lines changed

4 files changed

+149
-101
lines changed

‎docs/topics/command-line.md‎

Lines changed: 64 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,31 @@
11
[//]: # (title: Kotlin command-line compiler)
22

3-
Every Kotlin release ships with a standalone version of the compiler. You can download the latest version manually or via a package manager.
4-
5-
> Installing the command-line compiler is not an essential step to use Kotlin.
6-
> The common approach is to write Kotlin applications using IDEs or code editors with official Kotlin support,
7-
> such as [IntelliJ IDEA](https://www.jetbrains.com/idea/), [JetBrains Fleet](https://www.jetbrains.com/fleet/),
8-
> or [Android Studio](https://developer.android.com/studio).
9-
> They provide full Kotlin support right out of the box, no extra components needed.
10-
>
11-
> Learn how to [get started with Kotlin in an IDE](getting-started.md).
12-
>
13-
{type="note"}
14-
15-
## Install the compiler
3+
* Kotlin compiler
4+
* standalone version / EACH Kotlin release
5+
* _Example:_ [here](https://github.com/JetBrains/kotlin/releases/tag/v2.2.21)
6+
* 💡ways to get💡
7+
* [install it](#ways-to-install-the-compiler)
8+
* included | IDEs OR code editors / have official Kotlin support
9+
* [IntelliJ IDEA](https://www.jetbrains.com/idea/),
10+
* [JetBrains Fleet](https://www.jetbrains.com/fleet/),
11+
* [Android Studio](https://developer.android.com/studio)
12+
13+
## Ways to install the compiler
1614

1715
### Manual install
1816
* steps
19-
1. Download the latest version (`kotlin-compiler-%kotlinVersion%.zip`) from [GitHub Releases](%kotlinLatestUrl%).
17+
1. | [GitHub Kotlin Releases](https://github.com/JetBrains/kotlin/releases), download `kotlin-compiler-%kotlinVersion%.zip`
2018
2. Unzip | directory + OPTIONALLY add the `bin` | path
21-
3. Reason: 🧠 contains scripts / allows compiling & run Kotlin | Windows, macOS, and Linux. 🧠
19+
3. Reason: 🧠 contains scripts / allows compiling & run Kotlin | Windows, macOS, and Linux🧠
2220

2321
* | Windows, recommended option
2422

25-
{type="note"}
26-
2723
### SDKMAN!
2824
* TODO:
2925
An easier way to install Kotlin on UNIX-based systems, such as macOS, Linux, Cygwin, FreeBSD, and Solaris, is
30-
[SDKMAN!](https://sdkman.io). It also works in Bash and ZSH shells. [Learn how to install SDKMAN!](https://sdkman.io/install).
26+
[SDKMAN!](https://sdkman.io)
27+
* It also works in Bash and ZSH shells
28+
* [Learn how to install SDKMAN!](https://sdkman.io/install).
3129

3230
To install the Kotlin compiler via SDKMAN!, run the following command in the terminal:
3331

@@ -52,98 +50,63 @@ sudo snap install --classic kotlin
5250

5351
## Create and run an application
5452

55-
1. Create a simple console JVM application in Kotlin that displays `"Hello, World!"`.
56-
In a code editor, create a new file called `hello.kt` with the following code:
57-
58-
```kotlin
59-
fun main() {
60-
println("Hello, World!")
61-
}
62-
```
63-
64-
2. Compile the application using the Kotlin compiler:
65-
66-
```bash
67-
kotlinc hello.kt -include-runtime -d hello.jar
68-
```
69-
70-
* The `-d` option indicates the output path for generated class files, which may be either a directory or a **.jar** file.
71-
* The `-include-runtime` option makes the resulting **.jar** file self-contained and runnable by including the Kotlin runtime
72-
library in it.
73-
74-
To see all available options, run:
75-
76-
```bash
77-
kotlinc -help
78-
```
79-
80-
3. Run the application:
81-
82-
```bash
83-
java -jar hello.jar
84-
```
53+
* `kotlinc pathToKotlinFile.kt -include-runtime -d someJarFileOrSomeFolder`
54+
* `-include-runtime`
55+
* include Kotlin runtime | output
56+
* `-d someJarFileOrSomeFolder`
57+
* `-d someJarFile`
58+
* create a .jar file
59+
* \+ `-include-runtime` -> executable .jar
60+
* `-d someFolder`
61+
* create .class files
8562

8663
## Compile a library
8764

88-
If you're developing a library to be used by other Kotlin applications, you can build the **.jar** file without including
89-
the Kotlin runtime:
90-
91-
```bash
92-
kotlinc hello.kt -d hello.jar
93-
```
94-
95-
Since binaries compiled this way depend on the Kotlin runtime,
96-
you should ensure that it is present in the classpath whenever your compiled library is used
97-
98-
You can also use the `kotlin` script to run binaries produced by the Kotlin compiler:
65+
* library
66+
* uses
67+
* by OTHER Kotlin applications
9968

100-
```bash
101-
kotlin -classpath hello.jar HelloKt
102-
```
69+
* `kotlinc pathToKotlinFile.kt -d someJarFileOrSomeFolder`
70+
* build the **.jar** WITHOUT Kotlin runtime /
71+
* PathToKotlinFileKt
72+
* generated class
10373

104-
`HelloKt` is the main class name that the Kotlin compiler generates for the file named `hello.kt`.
74+
* if you want to run -> ways
75+
* `java -cp someJarFileOrSomeFolder:kotlinRuntime.jar GeneratedClass`
76+
* `kotlin -classpath someJarFileOrSomeFolder GeneratedClass`
10577

10678
## Run the REPL
10779

108-
You can run the compiler without parameters to have an interactive shell. In this shell, you can type any valid Kotlin code
109-
and see the results.
80+
* REPL
81+
* == Read-Eval-Print Loop
82+
* == interactive shell
83+
* `kotlinc`
84+
* WITHOUT arguments
85+
* uses
86+
* type any valid Kotlin code
11087

111-
<img src="kotlin-shell.png" alt="Shell" width="500"/>
88+
![](/docs/images/command-line/kotlin-shell.png)
11289

11390
## Run scripts
11491

115-
You can use Kotlin as a scripting language.
116-
A Kotlin script is a Kotlin source file (`.kts`) with top-level executable code.
117-
118-
```kotlin
119-
import java.io.File
120-
121-
// Get the passed in path, i.e. "-d some/path" or use the current path.
122-
val path = if (args.contains("-d")) args[1 + args.indexOf("-d")]
123-
else "."
124-
125-
val folders = File(path).listFiles { file -> file.isDirectory() }
126-
folders?.forEach { folder -> println(folder) }
127-
```
128-
129-
To run a script, pass the `-script` option to the compiler with the corresponding script file:
130-
131-
```bash
132-
kotlinc -script list_folders.kts -- -d <path_to_folder_to_inspect>
133-
```
134-
135-
Kotlin provides experimental support for script customization, such as adding external properties,
136-
providing static or dynamic dependencies, and so on.
137-
Customizations are defined by so-called _script definitions_ – annotated kotlin classes with the appropriate support code.
138-
The script filename extension is used to select the appropriate definition.
139-
Learn more about [Kotlin custom scripting](custom-script-deps-tutorial.md).
140-
141-
Properly prepared script definitions are detected and applied automatically when the appropriate jars are included
142-
in the compilation classpath. Alternatively, you can specify definitions manually by passing the `-script-templates` option
143-
to the compiler:
144-
145-
```bash
146-
kotlinc -script-templates org.example.CustomScriptDefinition -script custom.script1.kts
147-
```
148-
149-
For additional details, see the [KEEP-75](https://github.com/Kotlin/KEEP/blob/master/proposals/scripting-support.md).
92+
* == Kotlin -- as a -- scripting language
93+
* Kotlin script
94+
* == 💡`.kts` / top-level executable code💡
95+
* ALLOWED extensions
96+
* `.kts`
97+
* == standard Kotlin script
98+
* `.gradle.kts`
99+
* == Gradle Kotlin script
100+
* `.main.kts`
101+
* == AUTOMATIC dependencies script
102+
* custom extensions
103+
* _script definitions_
104+
* == annotated kotlin classes /
105+
* allows
106+
* customizations (add external properties, provide static or dynamic dependencies)
107+
* if the proper jars are included | compilation classpath -> detect & apply AUTOMATICALLY the prepared script definitions
108+
* OTHERWISE, specify MANUALLY -- by -- passing `-script-templates`
109+
* [KEEP-75](https://github.com/Kotlin/KEEP/blob/master/proposals/scripting-support.md)
110+
111+
* `kotlinc -script scriptPath.kts -- -d <path_to_folder_to_inspect>`
112+
* run a script

‎docs/topics/examples/command-line/HelloWorld.kt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
fun main() {
2+
println("Hello, World!")
3+
}

‎docs/topics/examples/command-line/README.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# prerequisites
2+
* [get kotlinc](../../command-line.md)
3+
4+
# how to run locally?
5+
## `-d outputPathToJarFile`
6+
* `kotlinc HelloWorld.kt -d HelloWorld.jar`
7+
* ways to run
8+
* `java -cp HelloWorld.jar:$KOTLIN_HOME/lib/kotlin-stdlib.jar HelloWorldKt`
9+
* `kotlin -classpath HelloWorld.jar HelloWorldKt`
10+
* `HelloWorldKt`
11+
* == generated class
12+
## `-include-runtime` + `-d outputPathToJarFile`
13+
* `kotlinc HelloWorld.kt -include-runtime -d HelloWorldWithRuntime.jar`
14+
* `java -jar HelloWorldWithRuntime.jar`
15+
## `-d outputPathToDirectory`
16+
* `kotlinc HelloWorld.kt -d output`
17+
* ways to run
18+
* `java -cp output:$KOTLIN_HOME/lib/kotlin-stdlib.jar HelloWorldKt`
19+
* `kotlin -classpath output HelloWorldKt`
20+
* HelloWorldKt
21+
* == generated class
22+
## `-include-runtime` + `-d outputPathToDirectory`
23+
* `kotlinc HelloWorld.kt -include-runtime -d outputWithRuntime`
24+
* `java -cp outputWithRuntime HelloWorldKt`
25+
26+
# run the REPL
27+
* `kotlinc`
28+
* `2+2`
29+
* `println("Welcome")`
30+
31+
# run scripts
32+
* `kotlinc -script script.kts` OR `kotlinc -script script.kts -- -d .`
33+
## ALLOWED extensions
34+
### `.kts`
35+
* `kotlinc -script script.kts`
36+
### `.gradle.kts`
37+
* `gradle hello`
38+
* execute the task
39+
### `.main.kts`
40+
* `kotlinc -script example.main.kts`
41+
### custom extensions
42+
* [CustomScriptDefinition.kt](CustomScriptDefinition.kt)
43+
* `kotlinc -cp kotlin-scripting-common-2.1.21.jar:kotlin-scripting-jvm-2.1.21.jar CustomScriptDefinition.kt -d custom-script.jar`
44+
* [kotlin-scripting-common-2.1.21.jar](https://repo1.maven.org/maven2/org/jetbrains/kotlin/kotlin-scripting-common/2.1.21/) & [kotlin-scripting-jvm-2.1.21.jar](https://repo1.maven.org/maven2/org/jetbrains/kotlin/kotlin-scripting-jvm/2.1.21/)
45+
* required
46+
* `kotlinc -cp custom-script.jar -script example.custom.kts`
47+
* Problems:
48+
* Problem1: "example.custom.kts:7:12: error: unresolved reference 'File'."
49+
* Solution: Script definition no se aplica correctamente
50+
* Añadir `import java.io.File` manualmente
51+
* Especificar tipos: `{ f: File -> ... }`
52+
* Las extensiones custom son complejas sin Gradle/Maven
53+
## script definitions
54+
* TODO:
55+
### if the proper jars are included | compilation classpath -> detect & apply AUTOMATICALLY the prepared script definitions
56+
* TODO:
57+
### `-script-templates`
58+
* TODO:

‎docs/topics/examples/command-line/script.kts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
#!/usr/bin/env kotlin
2+
3+
// Standard Kotlin script (.kts)
4+
import java.io.File
5+
6+
println("=== Kotlin Script Example ===")
7+
8+
// Get command line arguments
9+
val targetDir = if (args.isNotEmpty()) args[0] else "."
10+
println("Scanning directory: $targetDir")
11+
12+
// List all files and directories
13+
val dir = File(targetDir)
14+
if (dir.exists() && dir.isDirectory()) {
15+
dir.listFiles()?.forEach { file ->
16+
val type = if (file.isDirectory()) "[DIR]" else "[FILE]"
17+
val size = if (file.isFile()) " (${file.length()} bytes)" else ""
18+
println("$type ${file.name}$size")
19+
}
20+
} else {
21+
println("Directory not found: $targetDir")
22+
}
23+
24+
println("Script completed!")

0 commit comments

Comments
 (0)