Skip to content

Use scala-cli in Getting Started page #3072

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Oct 16, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 17 additions & 17 deletions _overviews/getting-started/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ To install them manually:
or [AdoptOpenJDK 8/11](https://adoptopenjdk.net/). Refer to [JDK Compatibility](/overviews/jdk-compatibility/overview.html) for Scala/Java compatibility detail.
1. Install [sbt](https://www.scala-sbt.org/download.html)

## Using the scala-cli command
## Using the Scala CLI

Create a file named `hello.scala` with following code:
```scala
Expand All @@ -156,15 +156,15 @@ def hello(): Unit =

You can define a method with `def` keyword and mark it as a "main" method with the `@main` annotation, designating it as
the entry point in program execution. The method's type is `Unit`, which means it does not return a value. `Unit`
can be thought of as an analogue to `void` keyword found in other languages. The `println` method will print the `"Hello World!"`
can be thought of as an analogue to `void` keyword found in other languages. The `println` method will print the `"Hello, World!"`
string to standard output.

To run the program, execute `scala-cli run hello.scala` command. The file will be compiled and executed, with console output
To run the program, execute `scala run hello.scala` command. The file will be compiled and executed, with console output
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To run the program, execute `scala run hello.scala` command. The file will be compiled and executed, with console output
To run the program, execute `scala run hello.scala` command from a terminal, within the `<project-dir>` directory. The file will be compiled and executed, with console output

similar to following:
```
$ scala-cli run hello.scala
Compiling project (Scala 3.4.2, JVM (20))
Compiled project (Scala 3.4.2, JVM (20))
$ scala run hello.scala
Compiling project (Scala 3.5.0, JVM (20))
Copy link
Member

@bishabosha bishabosha Sep 17, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there's also a liquid variable {{site.scala-3-version}} which can automatically update when we have a new release. e.g. its used on this page in the dropdown "Testing your setup"

Compiled project (Scala 3.5.0, JVM (20))
Hello, World!
```

Expand All @@ -183,9 +183,9 @@ the content of `name` argument.

To pass the arguments when executing the program, put them after `--`:
```
$ scala-cli run hello.scala -- Gabriel
Compiling project (Scala 3.4.2, JVM (20))
Compiled project (Scala 3.4.2, JVM (20))
$ scala run hello.scala -- Gabriel
Compiling project (Scala 3.5.0, JVM (20))
Compiled project (Scala 3.5.0, JVM (20))
Hello, Gabriel!
```

Expand All @@ -211,15 +211,15 @@ sequence of paths.

Execute the program. The dependency will be automatically downloaded. The execution should result in a similar output:
```
$ scala-cli run counter.scala
Compiling project (Scala 3.4.2, JVM (20))
Compiled project (Scala 3.4.2, JVM (20))
$ scala run counter.scala
Compiling project (Scala 3.5.0, JVM (20))
Compiled project (Scala 3.5.0, JVM (20))
4
```
The printed number should be 4: `hello.scala`, `counter.scala` and two hidden directories created automatically when a program is executed:
`.bsp` containing information about project used by IDEs, and `.scala-build` containing the results of compilation.

As it turns out, the `os-lib` library is part of Scala Toolkit, a collection of libraries recommended for tasks like testing,
As it turns out, the `os-lib` library is a part of Scala Toolkit, a collection of libraries recommended for tasks like testing,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TBH, I'm not sure showing the alternative with the toolkit is a good idea here. We should definitely link to the toolkit's home page as a "next steps" scenario. But with what we already showed above, the user already "got started". There is no need to switch to the toolkit for no immediate reason.

operating system interaction or handling JSONs. You can read more about libraries included in the toolkit [here](/toolkit/introduction.html).
To include the toolkit libraries, use `//> using toolkit default` directive:
```scala
Expand All @@ -234,12 +234,12 @@ def countFiles(): Unit =
This program is identical to the one above with the only difference being that other toolkit libraries will also be available to use
and their downloaded versions, instead of being specified by hand, will be the newest ones included in toolkit.

### Using scala-cli REPL
### Using REPL
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Using REPL
### Using the REPL


You can execute code interactively using REPL provided by `scala-cli` command. Execute `scala-cli` in console without any arguments.
You can execute code interactively using REPL provided by `scala` command. Execute `scala` in console without any arguments.
```
$ scala-cli
Welcome to Scala 3.4.2 (20-ea, Java OpenJDK 64-Bit Server VM).
$ scala
Welcome to Scala 3.5.0 (20-ea, Java OpenJDK 64-Bit Server VM).
Type in expressions for evaluation. Or try :help.

scala>
Expand Down
2 changes: 1 addition & 1 deletion _overviews/scala-book/two-types-variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ object Hello3 extends App {
As before:

- Save that code in a file named *Hello3.scala*
- Compile and run it with `scala-cli run Hello3.scala`
- Compile and run it with `scala run Hello3.scala`



Expand Down
14 changes: 7 additions & 7 deletions _overviews/scala3-book/methods-main-methods.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,10 @@ Scala 3 offers a new way to define programs that can be invoked from the command
{% endtab %}
{% endtabs %}

To run this program, save the line of code in a file named as e.g. *Hello.scala*---the filename doesn’t have to match the method name---and run it with `scala-cli`:
To run this program, save the line of code in a file named as e.g. *Hello.scala*---the filename doesn’t have to match the method name---and run it with `scala`:

```bash
$ scala-cli run Hello.scala
$ scala run Hello.scala
Hello, World
```

Expand Down Expand Up @@ -67,7 +67,7 @@ For example, given this `@main` method that takes an `Int`, a `String`, and a va
Pass the arguments after `--`:

```
$ scala-cli run happyBirthday.scala -- 23 Lisa Peter
$ scala run happyBirthday.scala -- 23 Lisa Peter
Happy 23rd Birthday, Lisa and Peter!
```

Expand All @@ -79,10 +79,10 @@ The program implemented from an `@main` method checks that there are enough argu
If a check fails, the program is terminated with an error message:

```
$ scala-cli run happyBirthday.scala -- 22
$ scala run happyBirthday.scala -- 22
Illegal command line after first argument: more arguments expected

$ scala-cli run happyBirthday.scala -- sixty Fred
$ scala run happyBirthday.scala -- sixty Fred
Illegal command line: java.lang.NumberFormatException: For input string: "sixty"
```

Expand Down Expand Up @@ -176,9 +176,9 @@ object happyBirthday {
{% endtab %}
{% endtabs %}

If you place that code in a file named *happyBirthday.scala*, you can then compile and run it with `scala-cli`, as shown previously:
If you place that code in a file named *happyBirthday.scala*, you can then compile and run it with `scala`, as shown previously:

```bash
$ scala-cli run happyBirthday.scala -- 23 Lisa Peter
$ scala run happyBirthday.scala -- 23 Lisa Peter
Happy 23rd Birthday, Lisa and Peter!
```
22 changes: 11 additions & 11 deletions _overviews/scala3-book/taste-hello-world.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,10 +47,10 @@ object hello {
{% endtabs %}
<!-- End tabs -->

Next, compile and run the code with `scala-cli`:
Next, compile and run the code with `scala`:

```bash
$ scala-cli run hello.scala
$ scala run hello.scala
```

When you run the command for the first time, two hidden directories will be created: `.bsp` and `.scala-build`. The first
Expand All @@ -59,8 +59,8 @@ of compilation.

The command should produce similar output:
```
Compiling project (Scala 3.4.2, JVM (20))
Compiled project (Scala 3.4.2, JVM (20))
Compiling project (Scala 3.5.0, JVM (20))
Compiled project (Scala 3.5.0, JVM (20))
Hello, World!
```

Expand Down Expand Up @@ -126,23 +126,23 @@ use the `+` operator on strings to join `"Hello, "` with `name` and `"!"`, makin

> You can learn more about using `val` by reading [Variables and Data Types](/scala3/book/taste-vars-data-types.html).

Then run the code with `scala-cli`. This time the program will pause after asking for your name,
Then run the code with `scala`. This time the program will pause after asking for your name,
and wait until you type a name and press return on the keyboard, looking like this:

```bash
$ scala-cli run helloInteractive.scala
Compiling project (Scala 3.4.2, JVM (20))
Compiled project (Scala 3.4.2, JVM (20))
$ scala run helloInteractive.scala
Compiling project (Scala 3.5.0, JVM (20))
Compiled project (Scala 3.5.0, JVM (20))
Please enter your name:
```

When you enter your name at the prompt, the final interaction should look like this:

```bash
$ scala-cli run helloInteractive.scala
Compiling project (Scala 3.4.2, JVM (20))
Compiled project (Scala 3.4.2, JVM (20))
$ scala run helloInteractive.scala
Compiling project (Scala 3.5.0, JVM (20))
Compiled project (Scala 3.5.0, JVM (20))
Please enter your name:
Alvin Alexander
Hello, Alvin Alexander!
Expand Down
18 changes: 9 additions & 9 deletions _overviews/tutorials/scala-for-java-programmers.md
Original file line number Diff line number Diff line change
Expand Up @@ -166,43 +166,43 @@ command (the greater-than sign `>` represents the shell prompt
and should not be typed):

```shell
> scala-cli run HelloWorld.scala
> scala run HelloWorld.scala
```

The program will be automatically compiled (with compiled classes somewhere in the newly created `.scala-build` directory)
and executed, producing a similar output:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
and executed, producing a similar output:
and executed, producing an output similar to:

("a similar output" in English refers to another output that was previously mentioned; there is no such thing here)

```
Compiling project (Scala 3.4.2, JVM (20))
Compiled project (Scala 3.4.2, JVM (20))
Compiling project (Scala 3.5.0, JVM (20))
Compiled project (Scala 3.5.0, JVM (20))
Hello, World!
```

#### Compiling From the Command Line

To compile the example, we use `scala-cli compile` command, which will invoke the Scala compiler, `scalac`. `scalac`
To compile the example, we use `scala compile` command, which will invoke the Scala compiler, `scalac`. `scalac`
works like most compilers: it takes a source file as argument, maybe
some options, and produces one or several output files. The outputs
it produces are standard Java class files.

```shell
> scala-cli compile HelloWorld.scala -d .
> scala compile HelloWorld.scala -d .
```

This will generate a few class files in the current directory (`-d .` option sets the compilation output directory). One of
This will generate a few class files in the current directory (`-d` option sets the compilation output directory). One of
them will be called `HelloWorld.class`, and contains a class
which can be directly executed using the `scala-cli` command, as the
which can be directly executed using the `scala` command, as the
following section shows.

#### Running From the Command Line

Once compiled, the program can be run using the `scala-cli run` command.
Once compiled, the program can be run using the `scala run` command.
Its usage is very similar to the `java` command used to run Java
programs, and accepts similar options. The above example can be
executed using the following command, which produces the expected
output:

```shell
> scala-cli run --main-class HelloWorld -classpath .
> scala run --main-class HelloWorld -classpath .
Hello, World!
```

Expand Down