From a088cec79e4c9bded62213df01559e862239bd10 Mon Sep 17 00:00:00 2001 From: Travis Lee Date: Fri, 24 Feb 2017 11:07:37 +0100 Subject: [PATCH] New getting-started series --- ...g-a-scala-project-with-intellij-and-sbt.md | 101 ++++++++++++++++++ .../getting-started-with-scala-in-intellij.md | 74 +++++++++++++ ...esting-scala-in-intellij-with-scalatest.md | 71 ++++++++++++ ...-with-scala-and-sbt-in-the-command-line.md | 82 ++++++++++++++ ...ting-scala-with-sbt-in-the-command-line.md | 72 +++++++++++++ 5 files changed, 400 insertions(+) create mode 100644 documentation/getting-started-intellij-track/building-a-scala-project-with-intellij-and-sbt.md create mode 100644 documentation/getting-started-intellij-track/getting-started-with-scala-in-intellij.md create mode 100644 documentation/getting-started-intellij-track/testing-scala-in-intellij-with-scalatest.md create mode 100644 documentation/getting-started-sbt-track/getting-started-with-scala-and-sbt-in-the-command-line.md create mode 100644 documentation/getting-started-sbt-track/testing-scala-with-sbt-in-the-command-line.md diff --git a/documentation/getting-started-intellij-track/building-a-scala-project-with-intellij-and-sbt.md b/documentation/getting-started-intellij-track/building-a-scala-project-with-intellij-and-sbt.md new file mode 100644 index 000000000..eedd7dd8a --- /dev/null +++ b/documentation/getting-started-intellij-track/building-a-scala-project-with-intellij-and-sbt.md @@ -0,0 +1,101 @@ +--- +title: Building a Scala project with IntelliJ and sbt +disqus: true +previous-page: getting-started-intellij-track/getting-started-with-scala-in-intellij +next-page: testing-scala-in-intellij-with-scalatest +--- + +In this tutorial, we'll see how to build a Scala project using [sbt](http://www.scala-sbt.org/0.13/docs/index.html). sbt is a popular tool for compiling, running, and testing Scala projects of any +size. Using a build tool such as sbt (or Maven/Gradle) becomes essential once you create projects with dependencies +or more than one code file. + We assume you've completed the +[first tutorial](http://scala-lang.org/documentation/getting-started-intellij-track/getting-started-with-scala-in-intellij.html). + +## Creating the project +In this section, we'll show you how to create the project in IntelliJ. However, if you're +comfortable with the command line, we recommend you try [Getting +started with Scala with sbt in the command line](http://scala-lang.org/documentation/getting-started-sbt-track/getting-started-with-scala-and-sbt-in-the-command-line.html) and then come back + here to the section "Writing Scala code". + +1. If you didn't create the project from the command line, open up IntelliJ and select "Create New Project" + * On the left panel, select Scala and on the right panel, select SBT + * Click **Next** + * Name the project "SBTExampleProject" +* If you already created the project in the command line, open up IntelliJ, select *Import Project* and open the `build.sbt` file for your project +* Make sure the **JDK Version** is 1.8 and the **SBT Version** is at least 0.13.13 +* Select **Use auto-import** so dependencies are automatically downloaded when available +* Select **Finish** + +## Understanding the directory structure +sbt creates many directories which can be useful once you start building +more complex projects. You can ignore most of them for now +but here's a glance at what everything is for: + +``` +- .idea (IntelliJ files) +- project (plugins and additional settings for sbt) +- src (source files) + - main (application code) + - java (Java source files) + - scala (Scala source files) <-- This is all we need for now + - scala-2.12 (Scala 2.12 specific files) + - test (unit tests) +- target (generated files) +- build.sbt (build definition file for sbt) + + +``` + + +## Writing Scala code +1. On the **Project** panel on the left, expand `SBTExampleProject` => `src` +=> `main` +* Right-click `scala` and select **New** => **Package** +* Name the package `example` and click **OK**. +* Right-click the package `example` and select **New** => **Scala class**. +* Name the class `Main` and change the **Kind** to `object`. +* Change the code in the class to the following: +``` +object Main extends App { + val ages = Seq(42, 75, 29, 64) + println(s"The oldest person is ${ages.max}") +} +``` + +Note: IntelliJ has its own syntax highlighter and sometimes your code is +correct even though IntelliJ indicates otherwise. You can always check +to see if sbt can run your project in the command line. + +## Running the project +1. From the **Run** menu, select **Edit configurations** +* Click the **+** button and select **SBT Task**. +* Name it `Run the program`. +* In the **Tasks** field, type `~run`. The `~` causes SBT to rebuild and rerun the project +when you save changes to a file in the project. +* Click **OK**. +* On the **Run** menu. Click **Run 'Run the program'**. +* In the code, change `currentYear - 1` to ` currentYear - 2` +and look at the updated output in the console. + +## Adding a dependency +Changing gears a bit, let's look at how to use published libraries to add +extra functionality to our apps. +1. Open up `build.sbt` and add the following line: + +``` +"org.scala-lang.modules" %% "scala-parser-combinators" % "1.0.5" + +``` +Here, `libraryDependencies` is a set of dependencies, and by using `+=`, +we're adding the [scala-parser-combinators](https://index.scala-lang.org/scala/scala-parser-combinators) dependency to the set of dependencies that sbt will go +and fetch when it starts up. Now, in any Scala file, you can import classes, +objects, etc, from scala-parser-combinators with a regular import. + +Find published libraries at [Scaladex](https://index.scala-lang.org/). + +## Next steps +Continue learning the language for free online with + [Scala Exercises](http://www.scala-exercises.org). +You can also check out our [list of learning resources](http://scala-lang.org/documentation/). + +[Up Next: Testing Scala in IntelliJ with scalatest](http://scala-lang.org/documentation/getting-started-intellij-track/testing-scala-in-intellij-with-scalatest.html) diff --git a/documentation/getting-started-intellij-track/getting-started-with-scala-in-intellij.md b/documentation/getting-started-intellij-track/getting-started-with-scala-in-intellij.md new file mode 100644 index 000000000..c89d13f71 --- /dev/null +++ b/documentation/getting-started-intellij-track/getting-started-with-scala-in-intellij.md @@ -0,0 +1,74 @@ +--- +title: Getting started with Scala in IntelliJ +disqus: true +next-page: building-a-scala-project-with-intellij-and-sbt +--- + +In this tutorial, we'll see how to build a minimal Scala project +using IntelliJ IDE with the Scala plugin. We'll have IntelliJ download +Scala for you. + +## Installation +1. Make sure you have the Java 8 JDK (also known as 1.8) + * Run `javac -version` in the command line and make sure you see + `javac 1.8.___` + * If you don't have version 1.8 or higher, [install the JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html) +* Install [IntelliJ Community Edition](https://www.jetbrains.com/idea/download/) +* Install the Scala plugin by following the instructions on +[how to install IntelliJ plugins](https://www.jetbrains.com/help/idea/installing-updating-and-uninstalling-repository-plugins.html) + +When we create the project, we'll install the latest version of Scala. +Note: If you want to open an existing Scala project, you can click **Open** +when you start IntelliJ. + +## Creating the Project +1. Open up IntelliJ and click **File** => **New** => **Project** +* On the left panel, select Scala. On the right panel, select Scala once again. +* Name the project **HelloWorld** +* Assuming this is your first time creating a Scala project with IntelliJ, +you'll need to install a Scala SDK. To the right of the Scala SDK field, +click the **Create** button. +* Select the highest version number (e.g. 2.12.1) and click **Download**. This might +take a few minutes but subsequent projects can use the same SDK. +* Once the SDK is created and you're back to the "New Project" window click **Finish**. + + +## Writing code + +1. On the **Project** pane on the left, right-click `src` and select +**New** => **Scala class**. +* Name the class `Hello` and change the **Kind** to `object`. +* Change the code in the class to the following: +```tut +object Hello extends App { + println("Hello, World!") +} +``` + +## Running it +* Right click on `Hello` in your code and select **Run 'Hello'**. +* You're done! + +## Experimenting with Scala +A good way to try out code samples is with Scala Worksheets + +1. In the project pane on the left, right click +`src` and select **New** => **Scala Worksheet**. +* Enter the following code into the worksheet: +```tut + +def square(x: Int) = x * x + +square(2) +``` + +As you change your code, you'll notice that it gets evaluated +in the right pane. + +## Next Steps +Now you know how to create a simple Scala project which can be used +for starting to learn the language. In the next tutorial, we'll introduce +an important build tool called sbt which can be used for simple projects +and production apps. + +Up next: [Building a Scala project with IntelliJ and sbt](building-a-scala-project-with-intellij-and-sbt.html) diff --git a/documentation/getting-started-intellij-track/testing-scala-in-intellij-with-scalatest.md b/documentation/getting-started-intellij-track/testing-scala-in-intellij-with-scalatest.md new file mode 100644 index 000000000..23cc9c49b --- /dev/null +++ b/documentation/getting-started-intellij-track/testing-scala-in-intellij-with-scalatest.md @@ -0,0 +1,71 @@ +--- +title: Testing Scala in IntelliJ with ScalaTest +disqus: true +previous-page: building-a-scala-project-with-intellij-and-sbt +--- + +There are multiple libraries and testing methodologies for Scala, +but in this tutorial, we'll demonstrate one popular option from the ScalaTest framework +called [FunSuite](http://www.scalatest.org/getting_started_with_fun_suite). +We assume you know [how to build a project in IntelliJ](http://scala-lang.org/documentation/getting-started-sbt-track/building-a-scala-project-with-intellij-and-sbt.html). + +## Setup +1. Create an sbt project in IntelliJ. +* Add the ScalaTest dependency to your build.sbt file: +``` +libraryDependencies += "org.scalatest" %% "scalatest" % "3.0.1" % "test" +``` +* this will cause sbt to pull down the ScalaTest library +* If you get a notification "build.sbt was changed", select **auto-import**. +* On the project pane on the left, expand `src` => `main`. +* Right-click on `scala` and select **New** => **Scala class**. +* Call it `CubeCalculator`, change the **Kind** to `object`, and click **OK**. +* Replace the code with the following: +```tut +object CubeCalculator extends App { + def cube(x: Int) = { + x * x * x + } +} +``` + +## Creating a test +1. On the project pane on the left, expand `src` => `test`. +* Right-click on `scala` and select **New** => **Scala class**. +* Name the class `CubeCalculatorTest` and click **OK**. +* Replace the code with the following: +``` +import org.scalatest.FunSuite + +class CubeCalculatorTest extends FunSuite { + test("CubeCalculator.cube") { + assert(CubeCalculator.cube(3) === 27) + } +} +``` +* In the source code, right-click `CubeCalculatorTest` and select **Run +'CubeCalculatorTest'**. + +## Understanding the code +Let's go over this line by line. + +* `class CubeCalculatorTest` means we are testing the object `CubeCalculator` +* `extends FunSuite` lets us use functionality of ScalaTest's FunSuite class +such as the `test` function +* `test` is function that comes from the FunSuite library that collects +results from assertions within the function body. +* `"CubeCalculator.cube"` is a name for the test. You can call it anything but +one convention is "ClassName.methodName". +* `assert` takes a boolean condition and determines whether the test passes or fails. +* `CubeCalculator.cube(3) === 27` checks whether the output of the `cube` function is +indeed 27. The `===` is part of ScalaTest and provides clean error messages. + +## Adding another test case +* Add another `assert` statement after the first one that checks for the cube +of `0`. +* Re-run the test again by right-clicking `CubeCalculatorTest` and selecting +'Run **CubeCalculatorTest**'. + +## Conclusion +You've seen one way to test your Scala code. You can learn more about +ScalaTest's FunSuite on the [official website](http://www.scalatest.org/getting_started_with_fun_suite). diff --git a/documentation/getting-started-sbt-track/getting-started-with-scala-and-sbt-in-the-command-line.md b/documentation/getting-started-sbt-track/getting-started-with-scala-and-sbt-in-the-command-line.md new file mode 100644 index 000000000..1c2d41eb9 --- /dev/null +++ b/documentation/getting-started-sbt-track/getting-started-with-scala-and-sbt-in-the-command-line.md @@ -0,0 +1,82 @@ +--- +title: Getting started with Scala and sbt in the command line +disqus: true +next-page: testing-scala-with-sbt-in-the-command-line +--- + +In this tutorial, you'll see how to create a Scala project from +a template. You can use this as a starting point for your own +projects. We'll use [sbt](http://www.scala-sbt.org/0.13/docs/index.html), the de facto build tool for Scala. sbt compiles, +runs, and tests your projects among other related tasks. +We assume you know how to use a terminal. + +## Installation +1. Make sure you have the Java 8 JDK (also known as 1.8) + * Run `javac -version` in the command line and make sure you see + `javac 1.8.___` + * If you don't have version 1.8 or higher, [install the JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html) +* Install sbt + * [Mac](http://www.scala-sbt.org/0.13/docs/Installing-sbt-on-Mac.html) + * [Windows](http://www.scala-sbt.org/0.13/docs/Installing-sbt-on-Windows.html) + * [Linux](http://www.scala-sbt.org/0.13/docs/Installing-sbt-on-Linux.html) + +## Create the project +1. `cd` to an empty folder. +* Run the following command `sbt new scala/hello-world.g8`. +This pulls the 'hello-world' template from GitHub. +It will also create a `target` folder, which you can ignore. +* When prompted, name the application `hello-world`. This will +create a project called "hello-world". +* Let's take a look at what just got generated +``` + +- hello-world + - project (sbt uses this to install manage plugins and dependencies) + - build.properties + - src + - main + - scala (All of your scala code goes here) + -Main.scala (Entry point of program) <-- this is all we need for now + build.sbt (sbt's build definition file) + +``` + +After you build your project, sbt will create more `target` directories +for generated files. You can ignore these. + +## Running the project +1. `cd` into `hello-world`. +* Run `sbt`. This will open up the sbt console. +* Type `~run`. The `~` is optional and causes sbt to re-run on every file save, +allowing for a fast edit/run/debug cycle. sbt will also generate a `target` directory +which you can ignore. + +## Modifying the code +1. Open the file `src/main/scala/Main.scala` in your favorite text editor. +* Change "Hello, World!" to "Hello, New York!" +* If you haven't stopped the sbt command, you should see "Hello, New York!" +printed to the console. +* You can continue to make changes and see the results. + +## Adding a dependency +Changing gears a bit, let's look at how to use published libraries to add +extra functionality to our apps. + +1. Open up `build.sbt` and add the following line: +``` +"org.scala-lang.modules" %% "scala-parser-combinators" % "1.0.5" + +``` +Here, `libraryDependencies` is a set of dependencies, and by using `+=`, +we're adding the [scala-parser-combinators](https://index.scala-lang.org/scala/scala-parser-combinators) dependency to the set of dependencies that sbt will go +and fetch when it starts up. Now, in any Scala file, you can import classes, +objects, etc, from scala-parser-combinators with a regular import. + +Find published libraries at [Scaladex](https://index.scala-lang.org/). + +## Next steps +Now that you know how to create a Scala project, you +can continue learning online for free with [Scala Exercises](http://scala-exercises.org) or choose +from our [list of educational resources](http://scala-lang.org/documentation/). + +[Up Next: Testing Scala with sbt in the command line](http://scala-lang.org/documentation/getting-started-sbt-track/testing-scala-with-sbt-in-the-command-line.html) diff --git a/documentation/getting-started-sbt-track/testing-scala-with-sbt-in-the-command-line.md b/documentation/getting-started-sbt-track/testing-scala-with-sbt-in-the-command-line.md new file mode 100644 index 000000000..b865f4daf --- /dev/null +++ b/documentation/getting-started-sbt-track/testing-scala-with-sbt-in-the-command-line.md @@ -0,0 +1,72 @@ +--- +title: Testing Scala with sbt and ScalaTest in the command line +disqus: true +previous-page: getting-started-with-scala-and-sbt-in-the-command-line +--- + +There are multiple libraries and testing methodologies for Scala, +but in this tutorial, we'll demonstrate one popular option from the ScalaTest framework +called [FunSuite](http://www.scalatest.org/getting_started_with_fun_suite). +We assume you know [how to create a Scala project with sbt](http://scala-lang.org/documentation/getting-started-sbt-track/getting-started-with-scala-and-sbt-in-the-command-line.html). + +## Setup +1. In the command line, create a new directory somewhere (e.g. `Documents`). +* `cd` into the directory and run `sbt new scala/scalatest-example.g8` +* Name the project `ScalaTestTutorial`. +* The project comes with ScalaTest as a dependency in the `build.sbt` file. +* `cd` into the directory and run `sbt test`. This will run the test suite +`CubeCalculatorTest` with a single test called `CubeCalculatorTest.cube`. +``` +sbt test +[info] Loading global plugins from /Users/travislee/.sbt/0.13/plugins +[info] Loading project definition from /Users/travislee/workspace/sandbox/my-something-project/project +[info] Set current project to scalatest-example (in build file:/Users/travislee/workspace/sandbox/my-something-project/) +[info] CubeCalculatorTest: +[info] - CubeCalculator.cube +[info] Run completed in 267 milliseconds. +[info] Total number of tests run: 1 +[info] Suites: completed 1, aborted 0 +[info] Tests: succeeded 1, failed 0, canceled 0, ignored 0, pending 0 +[info] All tests passed. +[success] Total time: 1 s, completed Feb 2, 2017 7:37:31 PM +``` + +## Understanding tests +1. Open up two files in a text editor: + * `src/main/scala/CubeCalculator.scala` + * `src/test/scala/CubeCalculatorTest.scala` +* In the file `CubeCalculator.scala`, you'll see how we define the function `cube`. +* In the file `CubeCalculatorTest.scala`, you'll see that we have a class +named after the object we're testing. +``` + import org.scalatest.FunSuite + + class CubeCalculatorTest extends FunSuite { + test("CubeCalculator.cube") { + assert(CubeCalculator.cube(3) === 27) + } + } + +``` + +Let's go over this line by line. + +* `class CubeCalculatorTest` means we are testing the object `CubeCalculator` +* `extends FunSuite` lets us use functionality of ScalaTest's FunSuite class +such as the `test` function +* `test` is function that comes from FunSuite that collects +results from assertions within the function body. +* `"CubeCalculator.cube"` is a name for the test. You can call it anything but +one convention is "ClassName.methodName". +* `assert` takes a boolean condition and determines whether the test passes or fails. +* `CubeCalculator.cube(3) === 27` checks whether the output of the `cube` function is +indeed 27. The `===` is part of ScalaTest and provides clean error messages. + +## Adding another test case +* Add another `assert` statement after the first one that checks for the cube +of `0`. +* Execute `sbt test` again to see the results. + +## Conclusion +You've seen one way to test your Scala code. You can learn more about +ScalaTest's FunSuite on the [official website](http://www.scalatest.org/getting_started_with_fun_suite). You can also check out other testing frameworks such as [ScalaCheck](https://www.scalacheck.org/) and [Specs2](https://etorreborre.github.io/specs2/).