How to build a Library in scala

Prerequisites

Knowledge of scala
Knowledge of working with git in terminal
Github account
Bintray account

Step 1.

Firstly we need an sbt project. In terminal navigate to the directory you want your library.

Then run...

  activator new

You want option 4 (minimal-scala) and then you want to give it a name.

Open it in your prefered code editing tool (intellij, sublime etc...)

Step 2.

Now you've created and opened your library project, you want to either amend or create your plugins.sbt file found under LIBRARY_NAME/project/plugins.sbt

You need to add these plugins to that file.

  addSbtPlugin("com.typesafe.sbt"   % "sbt-native-packager" % "1.2.0")
  addSbtPlugin("com.typesafe.play"  % "sbt-plugin"          % "2.5.16")
  addSbtPlugin("me.lessis"          % "bintray-sbt"         % "0.3.0")
  addSbtPlugin("com.github.gseitz"  % "sbt-release"         % "1.0.3")

sbt-native-packager Packages your library into a tgz.

sbt-plugin This is play. You don't have to have this if dont want your project to be play based.

bintray-sbt This plugin gives us the sbt commands to let us publish our library.

sbt-release This lets us version our library, but this won't be covered here.

Step 3.

In the root of your library there will a file called build.sbt we need to amend that.

  import com.typesafe.config.ConfigFactory
  import scala.util.{Try, Success, Failure}
  
  val btVersion: String = Try(ConfigFactory.load.getString("version")) match {
    case Success(ver) => ver
    case Failure(_)   => ""
  }
  
  name         := "example-library-name"
  version      := btVersion
  scalaVersion := "2.11.11"
  organisation := "com.example.libs"
  
  libraryDependencies ++= Seq(
    //Dependencies for your library
  )
  
  bintrayOrganisation                  := Some("example-org")
  bintrayReleaseOnPublish in ThisBuild := true
  bintrayRepository                    := "releases"
  bintrayOmitLicense                   := true

Lets explain the above code...

name Defines the name of library...is generated from the activator new command

btVersion Defines our library version

organisation Defines the libraries groupId

bintrayOrganisation This is optional, but if you have a bintray organisation, enter it here.

bintrayReleaseOnPublish This streamlines the publishing process a bit more i.e reduces the amount of commands you need to publish your library.

bintrayRepository This is where you on your bintray account you publish to.

Step 4.

This is your project write some code and tests!

Step 5.

Under your account on github you want to create a new repository for your library. Then in terminal (whilst your working directory is your library) you want to run git init to make your directory a git repo. You'll need to add a .gitignore file as well. Finally you want to git add commit push as normal.

Step 6.

Now that you have pushed your code to git you need to tag it. To achieve this...

  git tag -a 0.1.0 -m "0.1.0 example-library"
  git push origin --tags

This creates a tag on github. This can be found on github.com under releases on your repository.

Step 7.

On bintray.com on your account page there should be a Add new repository button. This needs to be same name as the value you've given bintrayRepository in your build.sbt file. The type needs to be maven.

When this is created it takes you to the repository you've just made. Next you need to press the Add new package button. The name needs to be same value as name in your build.sbt. Apache 2 will do for the license field. Version control should be the github link for your library.

Finally from the bintray site, you need your API key which can be found under account>Edit Profile> API key. Copy what it gives you.

Step 8.

Now it's time to publish your library. To ensure you're publishing the code you've just tagged on github, run...

  git checkout <TAG>

Now you've checked out your tag, run this command

  sbt -Dversion=<TAG> publish

On a note...going back to to where we defined bintrayReleaseOnPublish if we set this as false we would have to run

  sbt -Dversion=<TAG> bintrayRelease publish

Running this begins the publishing of your library...if it seems to hang, copy and paste your API key in, let it run (it will more than likely fail) then rerun the same publish command.

Step 9.

Hopefully your new shiny library is on bintray now. Now you need to grab your libraries ModuleID.

You can either go to bintray package you made on bintray.com and it will tell you or you can learn how make it your self.

Your module Id is made up of a groupId + artefactId + revision (in that order).

If we look back at our build.sbt file...look at...

  name         := "example-library-name"
  scalaVersion := "2.11.11"
  organisation := "com.example.libs"

organisation becomes our groupId

name combined with scalaVersion becomes our artefactId

Finally our git tag becomes our revision

For example, our ModuleId for above, assuming our git tag is 0.1.0 would be

  "com.example.libs" % "example-library-name_2.11" % "0.1.0"

Step 10.

Now we have our ModuleId, we can utilise our library in other sbt projects. Simply add something like this to your to your other projects build.sbt file.

  libraryDependencies ++= Seq(
    "com.example.libs" % "example-library-name_2.11" % "0.1.0"
  )

Note you may need to add a resolver if your project can't resolve your new library, add something like this...

  resolvers += "<Any name you want>" at "https://dl.bintray.com/<Your account or org name>/<Your bintray repo name>/"

chrisjwwalker/how_to_build_a_library_in_scala.md