basic_example

Basic Example

This shows how to build a simple OCaml project containing a library in ./lib/, a binary in ./bin/ that uses the library and tests of the library in ./test/ using Buck 2.

• Setup
• Buck 2 Targets
  • Examples
• Buck 2 Files

Setup

All you need to do to be able to build this project, is to install a new Opam switch and the needed packages.

In this directory basic_example, run the following command to create the Opam switch and install the packages configured in the file ./third-party/dromedary.json:

Use the actual path to dromedary.py instead of just dromedary.py in the example.

python3 dromedary.py -o third-party/BUCK third-party/dromedary.json

Then, the Opam switch's environment must be activated:

opam switch ./third-party
eval $(opam env --switch=./third-party --set-switch)

Now all needed packages should be installed and set up, so you can build and run the executable:

buck2 run //:bin

and the tests:

buck2 run //:test

Buck 2 Targets

• buck2 clean - deletes all generated files (in the directory ./buck-out/v2/).
• buck2 targets //... - lists all available targets, including all Opam packages. The packages have a prefix of root//third-party.
• buck2 build //... - builds all targets.
• buck2 run //:bin - run the generated executable. This is an alias for buck2 run //bin:basic_example.
• buck2 run //:test - run the generated executable. This is an alias for buck2 run //test:basic_example.

Examples

List only the targets of basic_example, without the Opam packages:

> buck2 targets //lib: //bin: //test: //:
Build ID: a1878688-a5d3-4e12-a25d-b90bb38d8648
Jobs completed: 2. Time elapsed: 0.0s.
root//:bin
root//:lib
root//:test
root//bin:basic_example
root//lib:basic_example
root//lib:basic_example.mli
root//lib:basic_example__
root//test:basic_example

Run the generated executable:

> buck2 run //:bin
File changed: root//README.md
Build ID: 9010eae3-43ac-4403-a5f8-25087c1aef7f
Jobs completed: 3. Time elapsed: 0.0s.
BUILD SUCCEEDED
Hello, World!
Btw. Fibonacci number F_10 is 55

Run the tests:

> buck2 run //:test
File changed: root//README.md
Build ID: 6e716b79-1c5b-4ef3-90ea-f1a58933892e
Jobs completed: 3. Time elapsed: 0.0s.
BUILD SUCCEEDED
qcheck random seed: 514228815
Testing `Fibonacci Tests'.
This run has ID `9WQ30JBU'.

  [OK]          Naive Fibonacci tests                     0   F0 is 0.
  [OK]          Naive Fibonacci tests                     1   F1 is 1.
  [OK]          Naive Fibonacci tests                     2   F2 is 1.
  [OK]          Naive Fibonacci tests                     3   F3 is 2.
  [OK]          Naive Fibonacci tests                     4   F4 is 3.
  [OK]          Naive Fibonacci tests                     5   F5 is 5.
  [OK]          Naive Fibonacci tests                     6   F6 is 8.
  [OK]          Naive Fibonacci tests                     7   F7 is 13.
  [OK]          Naive Fibonacci tests                     8   F8 is 21.
  [OK]          Naive Fibonacci tests                     9   F9 is 34.
  [OK]          Naive Fibonacci tests                    10   F10 is 55.
  [OK]          Compare naive and tail recursive          0   Using Quickcheck.

Full test results in `./OCaml-Buck-2-Examples/basic_example/_build/_tests/Fibonacci Tests'.
Test Successful in 0.882s. 12 tests run.

Buck 2 Files

• ./.buckroot - this marks the directory as the root of the Buck 2 directories. In real examples you might want to put all your projects in subdirectories of the Buck 2 root directory. This is an empty file.

• ./.buckconfig - Contains the configuration generated by buck2 init --git. Set the execution platform to the default one of the prelude.

  [build]
  execution_platforms = prelude//platforms:default

• ./toolchains/BUCK - The configuration of the toolchains to use. You always need C++ (system_cxx_toolchain) and Python (system_python_bootstrap_toolchain). The OCaml tool chain is system_ocaml_toolchain.

• ./third-party/ - This directory contains all third party dependencies and their configuration, like Opam packages. In a bigger Buck 2 configuration you want to use one subdirectory for each language or for each project, e.g. third-party/ocaml for all OCaml project dependencies or third-party/basic-example for the dependencies of basic_example, if for example Opam package versions differ from project to project.

• ./third-party/dromedary.json - This is the configuration of the Opam switch to create and the packages to install.

• ./third-party/BUCK - The configuration of the Opam packages. Generated by the ocaml-script dromedary.py, and should not be edited manually.

• ./BUCK - The main Buck 2 configuration file. Contains shorter aliases for the bin and test targets.

• ./bin/BUCK - The rules to build the binary.

• ./lib/BUCK - The rules to build the library.

• ./test/BUCK - The rules to build the test.

• ./prelude/ - Contains all toolchains and rules for all supported languages of Buck 2. A Git submodule.

• ./.merlin - Merlin configuration file for Merlin and the OCaml-LSP