Bring back library example by jfaustino · Pull Request #7430 · Project-OSRM/osrm-backend

jfaustino · 2026-03-26T01:14:46Z

Issue

Adresses #7266. No tests or changelog because it doesn't change the library itself, but I think the wiki may be improved.

Tasklist

self-review code for correctness and following the coding guidelines
[n/a] add tests (see testing)
update relevant wiki pages
[n/a] CHANGELOG.md entry (see how to)
review
adjust for comments

Requirements / Relations

N/A

Copilot

Pull request overview

Reintroduces and documents OSRM “library usage” examples by adding a C++ libosrm sample, a CMake find-module for libosrm, and refreshing the Node.js example and documentation.

Changes:

Modernize example/example.js to ESM imports and update its Monaco query example.
Add a C++ libosrm routing example (example/example.cpp) plus a CMake FindLibOSRM.cmake.
Add new documentation (docs/libosrm.md) and an example/README.md describing how to build/run the examples.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
example/example.js	Converts the Node.js example to ESM, updates threadpool sizing and example query URL.
example/example.cpp	Adds a standalone C++ `libosrm` “Route” example using `EngineConfig` + `OSRM::Route`.
example/cmake/FindLibOSRM.cmake	Introduces a pkg-config-based CMake find-module for locating `libosrm`.
example/README.md	Adds instructions for preparing test data and building/running the examples.
docs/libosrm.md	Adds introductory documentation for using OSRM as a C++ library.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-26T07:33:41Z

example/cmake/FindLibOSRM.cmake

+set(LibOSRM_CXXFLAGS ${output})
+set(LibOSRM_LIBRARY_DIRS ${PC_LibOSRM_LIBRARY_DIRS})
+
+find_path(LibOSRM_INCLUDE_DIR osrm/osrm.hpp
+  PATH_SUFFIXES osrm include/osrm include
+  HINTS ${PC_LibOSRM_INCLUDEDIR} ${PC_LibOSRM_INCLUDE_DIRS}
+  ~/Library/Frameworks


FindLibOSRM.cmake sets LibOSRM_INCLUDE_DIR but does not define LibOSRM_INCLUDE_DIRS. The example CMake build expects an *_INCLUDE_DIRS variable (plural), so includes will be empty and compilation will fail unless the caller guesses the singular variable name. Export LibOSRM_INCLUDE_DIRS (and ideally keep LibOSRM_INCLUDE_DIR as an alias) to make the find-module usable.

Copilot · 2026-03-26T07:33:41Z

example/cmake/FindLibOSRM.cmake

+find_library(TEST_LibOSRM_STATIC_LIBRARY Names osrm.lib libosrm.a
+  PATH_SUFFIXES osrm lib/osrm lib
+  HINTS ${PC_LibOSRM_LIBDIR} ${PC_LibOSRM_LIBRARY_DIRS}
+  ~/Library/Frameworks
+  /Library/Frameworks
+  /usr/local
+  /usr
+  /opt/local
+  /opt)
+find_library(TEST_LibOSRM_DYNAMIC_LIBRARY Names libosrm.dylib libosrm.so
+  PATH_SUFFIXES osrm lib/osrm lib
+  HINTS ${PC_LibOSRM_LIBDIR} ${PC_LibOSRM_LIBRARY_DIRS}
+  ~/Library/Frameworks
+  /Library/Frameworks
+  /usr/local
+  /usr
+  /opt/local
+  /opt)


TEST_LibOSRM_STATIC_LIBRARY and TEST_LibOSRM_DYNAMIC_LIBRARY are discovered but never used to influence LibOSRM_LIBRARIES / LibOSRM_DEPENDENT_LIBRARIES or the package-found check. This is confusing and can hide misconfigurations (e.g., pkg-config missing but libraries present). Either remove these lookups or use them as a fallback / validation in find_package_handle_standard_args.

Copilot · 2026-03-26T07:33:42Z

example/README.md

+```bash
+cd example/
+cmake ..
+cmake --build .
+```


The build instructions run cmake .. from inside example/, which points CMake at the repository root, not the example/ project (there is a dedicated example/CMakeLists.txt). This will configure/build the main OSRM project again instead of the example. Update the instructions to configure the example source directory explicitly (e.g., cmake -S . -B build from example/).

Copilot · 2026-03-26T07:33:42Z

docs/libosrm.md

+- [`TableParameters`](https://github.com/Project-OSRM/osrm-backend/blob/master/include/engine/api/table_parameters.hpp) - this is an example of parameter types the Routing Machine functions expect. In this case `Table` expects its own parameters as `TableParameters`. You can see it wrapping two vectors, sources and destinations --- these are indices into your coordinates for the table service to construct a matrix from (empty sources or destinations means: use all of them). If you ask yourself where coordinates come from, you can see `TableParameters` inheriting from `BaseParameters`.
+
+- [`BaseParameter`](https://github.com/Project-OSRM/osrm-backend/blob/master/include/engine/api/base_parameters.hpp) - this most importantly holds coordinates (and a few other optional properties that you don't need for basic usage); the specific parameter types inherit from `BaseParameters` to get these member attributes. That means your `TableParameters` type has `coordinates`, `sources` and `destination` member attributes (and a few other that we ignore for now).
+


The BaseParameters type name and member names are incorrect here: the class is BaseParameters (plural), and TableParameters has destinations (plural), not destination. This can mislead users copying the doc into real code.

Copilot · 2026-03-26T07:33:42Z

docs/libosrm.md

+- [Parameters for other services](https://github.com/Project-OSRM/osrm-backend/tree/master/include/engine/api) - here are all other `*Parameters` you need for other Routing Machine services.
+
+- [JSON](https://github.com/Project-OSRM/osrm-backend/blob/master/include/util/json_container.hpp) - this is a sum type resembling JSON. The Routing Machine service functions take a out-ref to a JSON result and fill it accordingly. It is currently implemented using [mapbox/variant](https://github.com/mapbox/variant) which is similar to [Boost.Variant](http://www.boost.org/doc/libs/1_55_0/doc/html/variant.html). There are two ways to work with this sum type: either provide a visitor that acts on each type on visitation or use the `get` function in case you're sure about the structure. The JSON structure is written down in the [HTTP API](#http-api).
+


The JSON section is out of date: util::json::Value is implemented with std::variant (and visited with std::visit), not mapbox/variant / Boost.Variant. Updating this avoids sending readers to the wrong APIs and libraries.

Copilot · 2026-03-26T07:33:42Z

example/example.cpp

+        std::cout << "Code: " << code << "\n";
+        std::cout << "Message: " << message << "\n";
+        return EXIT_FAILURE;
+    }


If status ever ends up neither Status::Ok nor Status::Error (or if additional enum values are added later), main falls off the end and returns 0, which would incorrectly signal success. Add a final else/default return path that reports an unexpected status and returns EXIT_FAILURE.

Suggested change

}

}

else

{

std::cerr << "Unexpected status value returned from OSRM Route\n";

return EXIT_FAILURE;

}

Copilot · 2026-03-26T07:33:43Z

example/example.js

+import OSRM from '../lib/index.js';
+
+process.env.UV_THREADPOOL_SIZE = Math.ceil(availableParallelism());



UV_THREADPOOL_SIZE is assigned after ESM static imports. Since static imports are evaluated before this assignment, the libuv threadpool size may already be initialized by the time the OSRM binding loads, making this setting ineffective. Set the env var before loading the binding (e.g., move it above and load OSRM via dynamic import), or document that it must be set externally before starting Node.

Copilot · 2026-03-26T07:33:43Z

example/example.js

 // Accepts a query like:
-// http://localhost:8888?start=13.414307,52.521835&end=13.402290,52.523728
+// http://localhost:8888?start=7.419758,43.731142&end=7.419505,43.736825
 app.get('/', function(req, res) {


Later in this example the route options object uses alternateRoute, but the Node.js binding expects the alternatives option (see test/nodejs/route.js). As written, the ?alternatives= query parameter won’t actually control alternative routing.

Copilot · 2026-03-26T07:33:43Z

docs/libosrm.md

@@ -0,0 +1,33 @@
+## Introduction
+
+OSRM can be used as a library (libosrm) via C++ instead of using it through the HTTP interface and `osrm-routed`. This allows for fine-tuning OSRM and has much less overhead. Here is a quick introduction into how to use `libosrm` in the upcoming v5 release.


This introduction says “upcoming v5 release”, but the repository is already past v5 (the JS package version is 6.x). This makes the new doc immediately read as outdated; please rephrase to be version-agnostic or refer to the current major version.

Suggested change

OSRM can be used as a library (libosrm) via C++ instead of using it through the HTTP interface and `osrm-routed`. This allows for fine-tuning OSRM and has much less overhead. Here is a quick introduction into how to use `libosrm` in the upcoming v5 release.

OSRM can be used as a library (libosrm) via C++ instead of using it through the HTTP interface and `osrm-routed`. This allows for fine-tuning OSRM and has much less overhead. Here is a quick introduction to how to use `libosrm`.

Copilot · 2026-03-26T07:33:43Z

docs/libosrm.md

+OSRM can be used as a library (libosrm) via C++ instead of using it through the HTTP interface and `osrm-routed`. This allows for fine-tuning OSRM and has much less overhead. Here is a quick introduction into how to use `libosrm` in the upcoming v5 release.
+
+Take a look at the example code that lives in the [example directory](https://github.com/Project-OSRM/osrm-backend/tree/master/example). Here is all you ever wanted to know about `libosrm`, that is a short description of what the types do and where to find documentation on it:
+


This new page isn’t linked from the VitePress nav/sidebar (see docs/.vitepress/config.js), and there don’t appear to be other docs linking to /libosrm yet. Add it to the docs navigation (or at least link it from docs/index.md) so users can discover it in the rendered documentation site.

Suggested change

For a general overview of OSRM and its HTTP API, see the [main documentation](./index.md).

jfaustino added 4 commits March 25, 2026 11:17

Bring back the library examples

c5abe44

Add the previous documentation for the library

d0f3f44

Add brief instructions on how to build the examples

40cc301

Change instructions order

5ef9bd3

DennisOSRM requested a review from Copilot March 26, 2026 07:27

Copilot started reviewing on behalf of DennisOSRM March 26, 2026 07:27 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Bring back library example#7430

Bring back library example#7430
jfaustino wants to merge 4 commits intoProject-OSRM:masterfrom
jfaustino:bring-back-library-example

jfaustino commented Mar 26, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		- [`TableParameters`](https://github.com/Project-OSRM/osrm-backend/blob/master/include/engine/api/table_parameters.hpp) - this is an example of parameter types the Routing Machine functions expect. In this case `Table` expects its own parameters as `TableParameters`. You can see it wrapping two vectors, sources and destinations --- these are indices into your coordinates for the table service to construct a matrix from (empty sources or destinations means: use all of them). If you ask yourself where coordinates come from, you can see `TableParameters` inheriting from `BaseParameters`.

		- [`BaseParameter`](https://github.com/Project-OSRM/osrm-backend/blob/master/include/engine/api/base_parameters.hpp) - this most importantly holds coordinates (and a few other optional properties that you don't need for basic usage); the specific parameter types inherit from `BaseParameters` to get these member attributes. That means your `TableParameters` type has `coordinates`, `sources` and `destination` member attributes (and a few other that we ignore for now).

		- [Parameters for other services](https://github.com/Project-OSRM/osrm-backend/tree/master/include/engine/api) - here are all other `*Parameters` you need for other Routing Machine services.

		- [JSON](https://github.com/Project-OSRM/osrm-backend/blob/master/include/util/json_container.hpp) - this is a sum type resembling JSON. The Routing Machine service functions take a out-ref to a JSON result and fill it accordingly. It is currently implemented using [mapbox/variant](https://github.com/mapbox/variant) which is similar to [Boost.Variant](http://www.boost.org/doc/libs/1_55_0/doc/html/variant.html). There are two ways to work with this sum type: either provide a visitor that acts on each type on visitation or use the `get` function in case you're sure about the structure. The JSON structure is written down in the [HTTP API](#http-api).

		import OSRM from '../lib/index.js';

		process.env.UV_THREADPOOL_SIZE = Math.ceil(availableParallelism());

		@@ -0,0 +1,33 @@
		## Introduction

		OSRM can be used as a library (libosrm) via C++ instead of using it through the HTTP interface and `osrm-routed`. This allows for fine-tuning OSRM and has much less overhead. Here is a quick introduction into how to use `libosrm` in the upcoming v5 release.

		OSRM can be used as a library (libosrm) via C++ instead of using it through the HTTP interface and `osrm-routed`. This allows for fine-tuning OSRM and has much less overhead. Here is a quick introduction into how to use `libosrm` in the upcoming v5 release.

		Take a look at the example code that lives in the [example directory](https://github.com/Project-OSRM/osrm-backend/tree/master/example). Here is all you ever wanted to know about `libosrm`, that is a short description of what the types do and where to find documentation on it:



	For a general overview of OSRM and its HTTP API, see the [main documentation](./index.md).

Uh oh!

Conversation

jfaustino commented Mar 26, 2026

Issue

Tasklist

Requirements / Relations

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants