Lagom build philosophy

§Lagom build philosophy

You are free to combine all your services in a single build, or build them individually.

Either way, Lagom uses sbt as a build tool and development environment.

§Builds: one vs. many

Lagom allows putting many services into one build. At the other extreme, you could have one build per service. Both approaches have advantages.

§One build

The advantage of one build is that often new features require simultaneous development on multiple services. Having those services in the same build makes for a frictionless development experience.

The disadvantage of one build is that as the number of developers working on that build grows, developers can get in each other’s way, especially if multiple teams are involved.

§Many builds

On the other hand, if each service is in its own build, each service can be changed independently. When changes culminate in a release, dependent services can upgrade and get the changes. Each service can move forward faster because each build is isolated.

When a system includes multiple builds, in order to work with services from other builds, you’ll need to do two things:

  • publish build products downstream
  • depend on build products from upstream builds

Splitting a system into multiple builds describes this in more detail.

§Our recommendation

We recommend when using Lagom to take a pragmatic approach and have one build per team. Dividing builds by team limits interference with each other’s work. Within a team, coordination is relatively easy, so multiple builds would just slow the team down.

As your system evolves and your organization evolves, your approach to dividing builds may need to change, too. Services may grow and need to be split, and so may teams. With this approach, it’s important not be afraid to refactor your builds to keep up with your organizational needs.

§Why sbt?

Whether you have one build or many, Lagom requires you build with sbt. That’s because sbt is much more than a build tool; it’s a development environment.

To offer an efficient, powerful, and convenient development experience, Lagom relies heavily on the following sbt features:

  • Tasks are fine-grained.
  • Each task may return a value.
  • The value returned by a task may be consumed by other tasks.

By contrast, typical build tools only offer coarse-grained tasks that communicate only by writing products to a filesystem. Tasks can’t otherwise communicate and be composed with each other, and must as a result rely heavily on convention.

Here are examples of fine-grained tasks in a sbt build. There is a task that defines where source directories are located, which then passes those locations to another task that finds the source files in those directories, which then passes those files to the compiler, returning a list of output artifacts. That list of artifacts can then be consumed by other tasks that handle, for example, packaging and deployment.

Because these tasks are so fine-grained, they are highly programmable, composable, introspectable, and customizable. In turn, this enables Lagom features such as:

  • Fast incremental recompilation
  • Hot reload (so can you immediately see the effects of changes)
  • Start and stop multiple services together (and in parallel)
  • Run tests in a variety of scenarios
  • Automatic injection of sensible configuration defaults (enabling a “it just works” experience)
  • Automatic enablement of plugins

Found an error in this documentation? The source code for this page can be found here. Please feel free to edit and contribute a pull request.