Tools for your own build
otok builds libraries for your app. It can also build the programs your own build runs on the development machine:
code generators such as protoc or flatc, a compiler of your project’s scripts, a CMake or Ninja of a fixed version.
Such a program comes from a recipe like a library does. It is pinned in the lock and built on each machine the same
way, so it does not have to be installed by hand on every developer’s machine and in CI.
protoc for a project that uses Protocol Buffers
Section titled “protoc for a project that uses Protocol Buffers”The runtime of Protocol Buffers is a library of the app. protoc, which turns .proto files into C++, is a tool of
the build machine. Both come from the recipe apotocki/protobuf, so one entry asks for both:
[otok]format = 1
[windows]build-on = ["windows/msvc"]
[deps.protobuf]recipe = "apotocki/protobuf"version = "~> 36.2"deliver = ["protoc"] # and protoc of the same version, for this machinedeliver asks otok to build the library’s recipe also as a tool for this machine, and to copy it into your project.
The tool has exactly the version the library got, so the generated code always matches the runtime it is compiled
against: otok update moves both together. otok install builds the runtime into Otok/protobuf/, as usual, and
protoc into Otok/tools/protobuf/:
Otok/├── protobuf/ the runtime, for the target├── otok-config.cmake└── tools/ ├── protobuf/bin/protoc.exe ├── otok-tools.cmake Otok_TOOL_protoc for CMake ├── otok-tools.props $(OtokTool_protoc) for MSBuild └── otok-tools.toml the same paths for scriptsdeliver lists the programs your build runs. A recipe may build several (otok info apotocki/protobuf shows its
[tool] programs); deliver = true takes all of them. A name the recipe does not build is an error.
Using it from CMake
Section titled “Using it from CMake”otok-tools.cmake sets Otok_TOOL_<program> to the absolute path of each program:
cmake_minimum_required(VERSION 3.28)project(hello CXX)set(CMAKE_CXX_STANDARD 17)
# the libraries of otok.toml, and the tools it deliversfind_package(Otok CONFIG REQUIRED PATHS "${CMAKE_SOURCE_DIR}/Otok" NO_DEFAULT_PATH NO_CMAKE_FIND_ROOT_PATH)include("${CMAKE_SOURCE_DIR}/Otok/tools/otok-tools.cmake")
add_custom_command( OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/hello.pb.cc" "${CMAKE_CURRENT_BINARY_DIR}/hello.pb.h" COMMAND "${Otok_TOOL_protoc}" --cpp_out "${CMAKE_CURRENT_BINARY_DIR}" -I "${CMAKE_SOURCE_DIR}/proto" hello.proto DEPENDS "${CMAKE_SOURCE_DIR}/proto/hello.proto" "${Otok_TOOL_protoc}")
add_executable(hello main.cpp "${CMAKE_CURRENT_BINARY_DIR}/hello.pb.cc")target_include_directories(hello PRIVATE "${CMAKE_CURRENT_BINARY_DIR}")target_link_libraries(hello PRIVATE otok::Protobuf)The same project builds on Linux and macOS with [linux] or [apple] in place of [windows]. There the program is
protoc-36.2.0 (bin/protoc is a link to it), which is why the build should take the path from the variable rather
than spell it out.
Using it from MSBuild
Section titled “Using it from MSBuild”Import otok-tools.props (from Directory.Build.props, beside otok.props) and use $(OtokTool_protoc) in a custom
build step:
<Import Project="$(MSBuildThisFileDirectory)Otok\tools\otok-tools.props" Condition="Exists('$(MSBuildThisFileDirectory)Otok\tools\otok-tools.props')" /><CustomBuild Include="proto\hello.proto"> <Command>"$(OtokTool_protoc)" --cpp_out="$(IntDir)." -I proto hello.proto</Command> <Outputs>$(IntDir)hello.pb.cc;$(IntDir)hello.pb.h</Outputs></CustomBuild>A character of a program’s name other than a letter, a digit or _ becomes _ in these names: the program
annium-compile is Otok_TOOL_annium_compile and $(OtokTool_annium_compile).
Using it from scripts
Section titled “Using it from scripts”Gradle, Xcode build phases and shell scripts can read Otok/tools/otok-tools.toml. It gives each program’s path
relative to the file:
format = 1
[programs."protobuf"]"protoc" = "protobuf/bin/protoc.exe"protoc=Otok/tools/$(sed -n 's/^"protoc" = "\(.*\)"$/\1/p' Otok/tools/otok-tools.toml)"$protoc" --cpp_out=gen -I proto proto/hello.protoA tool on its own
Section titled “A tool on its own”A tool that is not a library of your app, such as a compiler of your project’s scripts, is delivered from
[tool-deps], with the same deliver:
[tool-deps.annium-compile]recipe = { git = "https://example.com/recipes.git", rev = "<commit>", path = "annium-compile" }deliver = trueA [tool-deps.protobuf] entry beside [deps.protobuf] is not needed. Add one only to choose the options, flags or
standard of the tool: the library and its tool are separate builds, and the options of [deps.protobuf] are the
library’s alone. It names the same recipe, and its version must allow the one the library gets.
How it behaves
Section titled “How it behaves”- The machine’s own build. A delivered tool is built for the machine
otok installruns on: a Windows program on Windows, a macOS one on a Mac. A project built on several systems locks the tool for each of them, like the tools recipes build with. - Nothing beside it. Tools are built static and in release, so
Otok/tools/<library>/needs nothing but the system’s libraries. It holds whatever the recipe installs, not onlybin/and not only the programs listed indeliver; the files of the consumer name those listed. - Up to date. A tool is copied again only when it changed. One that is no longer delivered is removed, and
without any delivered tool
Otok/tools/is removed too. AddOtok/to.gitignore: it is made byotok install. - In CI.
otok install --lockedbuilds or fetches the same tool from the cache, so CI runs theprotocthe developers run. See Continuous integration. - From a working tree. A tool of your own, such as a compiler of your project’s scripts, can be built from its
working tree with
otok.dev.tomllike any library (Working on a library). Your build then always runs the compiler of the sources you have. - Another place.
tools-outputin[otok]moves the tools elsewhere in the project (defaultOtok/tools).
A tool is a recipe with [tool] programs, built where slice.is_tool holds
(Writing a recipe). A program that is a script run by another tool (Meson, run by Python)
cannot be delivered, since its interpreter is not.
© 2026 Alexander A Pototskiy and contributors. Text CC BY 4.0; examplesCC0.