Getting Started tutorial series

travissarles · travissarles · commit 3dfa4083bada · 2017-04-27T11:40:56.000+02:00
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
@@ -0,0 +1,102 @@
+---
+title: Building a Scala Project with IntelliJ and sbt
+layout: inner-page-no-masthead
+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](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 and sbt in the Command Line]({{site.baseurl}}/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"
+1. 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
+1. Make sure the **JDK Version** is 1.8 and the **SBT Version** is at least 0.13.13
+1. Select **Use auto-import** so dependencies are automatically downloaded when available
+1. 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`
+1. Right-click `scala` and select **New** => **Package**
+1. Name the package `example` and click **OK**.
+1. Right-click the package `example` and select **New** => **Scala class**.
+1. Name the class `Main` and change the **Kind** to `object`.
+1. 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**
+1. Click the **+** button and select **SBT Task**.
+1. Name it `Run the program`.
+1. 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.
+1. Click **OK**.
+1. On the **Run** menu. Click **Run 'Run the program'**.
+1. 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]({{site.baseurl}}/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](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
@@ -0,0 +1,78 @@
+---
+title: Getting Started with Scala in IntelliJ
+layout: inner-page-no-masthead
+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)
+1. Install [IntelliJ Community Edition](https://www.jetbrains.com/idea/download/)
+1. 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**
+1. On the left panel, select Scala. On the right panel, select Scala once again.
+1. Name the project **HelloWorld**
+1. 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.
+1. 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.
+1. 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**.
+1. Name the class `Hello` and change the **Kind** to `object`.
+1. Change the code in the class to the following:
+
+```
+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**.
+1. Enter the following code into the worksheet:
+
+
+```
+
+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
@@ -0,0 +1,77 @@
+---
+title: Testing Scala in IntelliJ with ScalaTest
+layout: inner-page-no-masthead
+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](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"
+```
+
+1. this will cause sbt to pull down the ScalaTest library
+1. If you get a notification "build.sbt was changed", select **auto-import**.
+1. On the project pane on the left, expand `src` => `main`.
+1. Right-click on `scala` and select **New** => **Scala class**.
+1. Call it `CubeCalculator`, change the **Kind** to `object`, and click **OK**.
+1. Replace the code with the following:
+
+```
+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`.
+1. Right-click on `scala` and select **New** => **Scala class**.
+1. Name the class `CubeCalculatorTest` and click **OK**.
+1. Replace the code with the following:
+
+```
+import org.scalatest.FunSuite
+
+class CubeCalculatorTest extends FunSuite {
+  test("CubeCalculator.cube") {
+    assert(CubeCalculator.cube(3) === 27)
+  }
+}
+```
+
+1. 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
+1. Add another `assert` statement after the first one that checks for the cube
+of `0`.
+1. 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
@@ -0,0 +1,86 @@
+---
+title: Getting Started with Scala and sbt in the Command Line
+layout: inner-page-no-masthead
+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)
+1. 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.
+1. 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.
+1. When prompted, name the application `hello-world`. This will
+create a project called "hello-world".
+1. 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`.
+1. Run `sbt`. This will open up the sbt console.
+1. 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.
+1. Change "Hello, World!" to "Hello, New York!"
+1. If you haven't stopped the sbt command, you should see "Hello, New York!"
+printed to the console.
+1. 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](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
