Claro is a statically compiled JVM language whose goal is first and foremost to provide you with the tools for reasoning about program design and construction using a very clear and direct mental model - data flowing through a systems of steps where new data may be produced, and existing data may be updated by the system at each step. This stated mental model is intentionally simple. Where it may be vague, I hope to add clarity in the rest of these intro docs.
Where other languages tend to mostly fall into the "Object-Oriented" (Java, Python, etc) paradigm, or the "Functional Programming" (Haskell, Elm, Roc, etc) paradigm, Claro eschews both of these extremes and lands somewhere more closely resembling a mix of procedural and declarative programming. Claro aims to be easily digestible to programmers coming from other paradigms by actually striving to add as few totally novel features as possible - only adding net-new ideas where they can be easily understandable to any user with moderate effort and only after the net-new idea has proven to provide some substantial, and observable benefit in the real world. Claro is not an esoteric language to be marvelled at by experts, or language geeks (like myself). Claro is a practical language whose mission is to help make writing readable, extensible, and performant programs significantly easier than one would achieve using existing languages and tools. Rather than depend heavily on layers of frameworks to achieve things like dependency injection, safe concurrency and more, Claro gives you powerful capabilities out of the box.
Learning Claro will involve a bit of unlearning of previous language principles, but will leave you with a single, well-lit path.
Please understand that these docs are a work in progress, and while they do cover a large chunk of the language features, there is still more documentation to come including better examples and clearer explanations.
Learn Claro By Example!
Check out the example Claro programs.
Create your own Claro Project with Bazel!
1 - Install Bazel (Required)
Simply install Bazel - instructions to install via Bazelisk can be found here.
2 - Auto-Generate Your Project
create_claro_project.sh from the latest Release
and run this command:
$ ./create_claro_project.sh <project name>
More details at tools/README.md
2 (Alternative) - Manually Copy Configuration of Example Project
Follow the example Claro project configuration at examples/bzlmod/.
NOTE: In your MODULE.bazel file, you'll want to choose the latest release published to: https://registry.bazel.build/modules/claro-lang
Building Claro Programs
As Claro projects are fundamentally built on the Bazel build system, building a Claro
program simply requires running a single
bazel build ... command. For example, if you wanted to build the example
//examples/claro_programs/atoms.claro, you can simply run the corresponding
claro_binary(name = "atoms", ...) target located at
//examples/claro_programs/BUILD using the below command from any
directory within the claro-lang project:
$ bazel build //examples/claro_programs:atoms
This will invoke the claro compiler to do type checking and codegen for the specified Claro program. You can build any Bazel target this way.
Running Claro Programs
A Claro program can be executed in two different ways:
$ bazel run ...
This is the most straightforward approach, and the one that you'll use most often when in local development. Simply use
bazel run ... command to have Bazel build the specified executable Claro program, and then immediately run the
generated executable. Note that this command is only supported on Bazel targets that produce an executable output, in
Claro's case, that means you can only
bazel run ... a
claro_binary() target, and not a
It's worth noting that this approach prioritizes build time, but does not generate a portable executable. For a portable executable, see the section below.
Building and Running a Prebuilt Executable Jar
In order to build a portable, executable Jar file that can be run anywhere where a JVM is available, you will have to
bazel build ... a "deploy Jar". This can be done by building the
foo_deploy.jar Bazel target that the
claro_binary(name = foo, ...) rule generates automatically. For example, to build a portable executable for the
claro_binary() target at
$ bazel build //examples/claro_programs:atoms_deploy.jar
The above command will produce output like the following:
➜ claro-lang git:(main) ✗ bazel build //examples/claro_programs:atoms_deploy.jar + INFO: Analyzed target //examples/claro_programs:atoms_deploy.jar (0 packages loaded, 0 targets configured). INFO: Found 1 target... Target //examples/claro_programs:atoms_deploy.jar up-to-date: bazel-bin/examples/claro_programs/atoms_deploy.jar INFO: Elapsed time: 0.174s, Critical Path: 0.00s INFO: 1 process: 1 internal. INFO: Build completed successfully, 1 total action
Now, the generated "deploy Jar" is listed as being located at
can now execute it using the following command:
java -jar bazel-bin/examples/claro_programs/atoms_deploy.jar
That's it! Now, this "deploy Jar" can be taken and run anywhere with a JVM.