> Documentation version: 0.4.0. [HTML page](https://lukewilliamboswell.github.io/roc-time/getting-started.html)

<a id="getting-started"></a>

# Run your first application

You’ll run a booking application that reads opening hours and two bookings, then prints the free windows in UTC. You’ll need a Roc compiler and the examples archive from a package release.

<a id="get-the-examples-archive"></a>

## Get the examples archive

Choose a [release](https://github.com/lukewilliamboswell/roc-time/releases), download ` roc-time-examples-<version>.zip ` and extract it. Install the Roc nightly named in that release’s notes. A later nightly may work too; check the compatibility results if it fails.

The archive already contains the package URLs you need. Keep each application’s whole folder: ` main.roc ` imports the neighboring module that does the calculation.

<a id="run-the-booking-example"></a>

## Run the booking example

From the extracted folder:

``` sh
roc version
roc examples/booking_exchange/main.roc
```

The version command lets you compare your compiler with the release notes. The application prints:

``` text
Restored available booking windows (UTC)
2026-06-15T09:00:00.000000Z/2026-06-15T10:00:00.000000Z
2026-06-15T12:00:00.000000Z/2026-06-15T15:00:00.000000Z
2026-06-15T16:00:00.000000Z/2026-06-15T17:00:00.000000Z
```

Each line is a free interval with its start and end separated by ` / `. The shop opens at 09:00 UTC and closes at 17:00. One booking arrives as 12:00–14:00 at UTC+02:00, which is 10:00–12:00 UTC; the other occupies 15:00–16:00 UTC.

Roc downloads the content-addressed package dependencies on first use. You don’t need Python or a separate example runner.

<a id="change-an-input"></a>

## Change an input

Open ` examples/booking_exchange/main.roc `. Remove the second booking, ` 2026-06-15T15:00:00Z/2026-06-15T16:00:00Z `, from the list and run the application again. The two afternoon windows join into a single 12:00–17:00 UTC window.

You can also move a booking by editing its timestamps. Keep the ` Z ` or numeric offset: without one, a local clock time doesn’t tell the application where the booking belongs on the timeline. ` BookingExchange.roc ` parses the text and subtracts the occupied time through the public library API.

<a id="use-the-library-in-your-own-app"></a>

## Use the library in your own app

Copy the ` time ` dependency from an archived example’s header into your application’s header, keeping your own platform declaration. This gives you the exact package URL tested for that release. The library doesn’t pin your compiler.

For named zones, also copy the ` zones ` dependency from the archived ` examples/staffing/main.roc `. It supplies timezone data separately, so an application working only with explicit offsets doesn’t need the database.

If you copied an example from the repository instead, its relative dependencies point at the local checkout. [Versions](versions.md#versions) explains how to keep source, packages and API documentation together.

<a id="choose-your-next-step"></a>

## Choose your next step

- [Find availability](booking.md#booking): timestamps, spans and coverage.


- [Calculate dates and handle clock changes](calendar-zones.md#calendar-zones): due dates and local appointments.


- [Generate schedules](schedules.md#schedules): recurring bookings, exceptions and bounded queries.


If an imported API is missing, compare your package URL with the example’s
version before changing the compiler or rewriting imports.