Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 125 additions & 0 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
# Repository guidance

`cel-std` is a C++20 library that installs the Rust CEL standard library's
35 retained `f64` operations into the C++ CEL parser. Its public CMake target
is `cel::std`; the installed package name is `cel-std`.

## Build, test, and lint

Run commands from the repository root. Use CMake 3.24 or later, a C++20
compiler, and Ninja for the presets. CPM downloads pinned dependencies into
`.cache/cpm`; dependency declarations live in `CMakeLists.txt`.

Configure, build, and run the unit-test executable and compiled example:

```sh
cmake --preset=test
cmake --build --preset=test --parallel 2
ctest --preset=test --output-on-failure --no-tests=error
```

CTest registers `std_test` and `example`, not individual doctest cases.
Run a single doctest case directly after building:

```sh
build/test/std_test --list-test-cases
build/test/std_test \
--test-case="sin_cos returns a structural sine then cosine tuple"
```

Run only the example through CTest:

```sh
ctest --preset=test -R '^example$' --output-on-failure
```

Run static analysis with the repository's `.clang-tidy` configuration and
`clang-tidy` on `PATH`:

```sh
cmake --preset=clang-tidy
cmake --build --preset=clang-tidy --parallel 2
ctest --preset=clang-tidy
```

Use `.clang-format` for C++ formatting.

Build the Release library without tests:

```sh
cmake --preset=default
cmake --build --preset=default --parallel 2
```

Build documentation with Doxygen 1.13.1 or later:

```sh
cmake --preset=docs
cmake --build --preset=docs
```

The generated site is `build/docs/html/index.html`. CI tests Ubuntu GCC,
Ubuntu Clang, macOS, and Windows, runs clang-tidy, and checks installed
package artifacts. The docs CI job runs on published releases.

## Architecture

- `include/cel/std.hpp` exposes `cel::stdlib::install(cel::op_lookup&)`.
`src/std.cpp` contains the registrations and numeric adapters; parsing
and execution belong to the external `cel-parser` and `cel-runtime`
libraries. `cel::parser` is a public dependency and supplies the runtime
transitively.
- The internal `add<Function, A...>` helper registers both the typed
operation with `register_op` and a stateless `function_marker` with
`register_function`. Preserve both registrations: ordinary calls,
receiver calls, and calls inside closure bodies use this setup.
- Install into a lookup before moving it into `cel::parser`. Compile with
`parse_str`, prepare the C++ result type, and execute with a caller-owned
`cel::raw_stack`. Emitted programs retain their callbacks and can outlive
the parser.
- `cpp_library_setup` from `stlab/cpp-library` defines the library, tests,
example, documentation, and packaging. Prefer its supported parameters
over duplicating its defaults. The `init` preset forces template
regeneration, including presets and CI; do not use it as a normal build.
- Installation is non-recursive: install runtime, parser, and this library
separately, in that order. See `docs/tutorial.md` for the
`CPM_USE_LOCAL_PACKAGES` and `CMAKE_PREFIX_PATH` commands.

## Numeric and registration conventions

- Keep the port limited to `double` operands and results, except for
`sin_cos`, which returns a structural CEL tuple adapted as
`std::tuple<double, double>`. Integer and `f32` overloads and `powi` are
outside this port. `docs/reference.md` lists the retained signatures.
- Receiver syntax supplies the first operand and must match ordinary-call
argument order. Install each exact signature once per lookup; unrelated
registrations and disjoint overloads must remain usable. Registration
failures propagate, and installation is not transactional.
- Preserve Rust operation semantics rather than blindly substituting
similarly named C++ functions. Existing adapters handle nearest-even
rounding, Euclidean remainder, and clamp validation. `mul_add` uses
`std::fma` for a single rounding step.
- Require IEEE 754 binary64 and avoid fast-math modes that discard NaNs,
infinities, or signed zeros. `round_ties_even` must remain independent of
the ambient rounding mode without changing it. Compare transcendental
results with tolerances; NaN payloads and signs are unspecified.
- Invalid clamp bounds throw
`std::invalid_argument("invalid clamp bounds")`, including NaN bounds.
Other numeric domain failures produce NaN or infinity as specified by
the linked CEL language book. Unsupported signatures fail during parsing
with `cel::parse_error`.

## Tests and documentation

`tests/std_test.cpp` owns the doctest main. Its `evaluate<R>` helper destroys
the parser before executing the emitted program, so expression tests also
exercise callback lifetime. The scalar case table covers both ordinary and
receiver syntax; separate cases cover closures, overload coexistence,
rejected signatures, floating-point edge cases, and tuple structure.

`examples/example.cpp` is compiled and run by CTest and included directly
in the Doxygen tutorial. Keep that example consistent with the tutorial.
`README.md`, `docs/tutorial.md`, `docs/reference.md`, and the public header
feed the generated documentation. Use the CEL language-book links in
`docs/reference.md` for operation contracts, accounting for this port's
smaller type and operation set.
31 changes: 5 additions & 26 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -1,48 +1,27 @@
cmake_minimum_required(VERSION 3.24)

include(cmake/CPM.cmake)
CPMAddPackage("gh:stlab/cpp-library@6.0.1")
CPMAddPackage("gh:stlab/cpp-library@6.1.0")
include("${cpp-library_SOURCE_DIR}/cpp-library.cmake")
cpp_library_enable_dependency_tracking()

project(std LANGUAGES CXX)

include(CTest)

option(CEL_INSTALL "Enable installation for CEL libraries" ${PROJECT_IS_TOP_LEVEL})
CPMAddPackage("gh:stlab/cel-parser@1.0.2")

# Initialize the shared CEL_INSTALL default before same-namespace dependencies.
cpp_library_setup(
DESCRIPTION "The f64 CEL standard library"
NAMESPACE cel
HEADERS std.hpp
SOURCES std.cpp
TESTS std_test.cpp
EXAMPLES example.cpp
LICENSE_FILES licenses/CPM-MIT.txt
DOCS_INPUTS README.md docs/tutorial.md docs/reference.md
DOCS_EXCLUDE_SYMBOLS cel::op_lookup
DOCS_OPTIONS
"USE_MDFILE_AS_MAINPAGE = ${CMAKE_CURRENT_SOURCE_DIR}/README.md"
"EXCLUDE_SYMBOLS = cel::op_lookup"
"WARN_AS_ERROR = YES"
"FULL_PATH_NAMES = NO"
"STRIP_FROM_INC_PATH = ${CMAKE_CURRENT_SOURCE_DIR}/include"
)
cpp_library_map_dependency("cel::parser" "cel-parser 1.0.2 CONFIG")
CPMAddPackage("gh:stlab/cel-parser@1.1.1")
target_link_libraries(std PUBLIC cel::parser)
if(CEL_INSTALL)
install(FILES LICENSE licenses/CPM-MIT.txt
DESTINATION "${CMAKE_INSTALL_DATADIR}/licenses/cel-std")
endif()

if(PROJECT_IS_TOP_LEVEL AND BUILD_TESTING)
configure_file(tests/consumer.cmake.in consumer.cmake @ONLY)
foreach(mode source installed)
if(mode STREQUAL "installed" AND NOT CEL_INSTALL)
continue()
endif()
add_test(NAME consumer_${mode}
COMMAND "${CMAKE_COMMAND}" "-DMODE=${mode}" "-DCONFIG=$<CONFIG>"
-P "${CMAKE_CURRENT_BINARY_DIR}/consumer.cmake")
set_tests_properties(consumer_${mode} PROPERTIES TIMEOUT 300)
endforeach()
endif()
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ compiled example and installed-package instructions.

## Build and test

Configure, build, and run all unit, example, and consumer tests:
Configure, build, and run all unit and example tests:

```sh
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_DOCS=OFF
Expand Down
22 changes: 18 additions & 4 deletions docs/tutorial.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,17 +69,31 @@ fails.

## Consume an installed package

To install a release build, run:
Install `cel-runtime` 1.1.2 and `cel-parser` 1.1.1 separately before installing
`cel-std`. From the `cel-std` source directory, run:

```sh
cmake -S /PATH/TO/cel-runtime -B build/runtime -DCMAKE_BUILD_TYPE=Release \
-DBUILD_TESTING=OFF -DBUILD_DOCS=OFF
cmake --build build/runtime --config Release
cmake --install build/runtime --config Release --prefix /PATH/TO/PREFIX

cmake -S /PATH/TO/cel-parser -B build/parser -DCMAKE_BUILD_TYPE=Release \
-DBUILD_TESTING=OFF -DBUILD_DOCS=OFF -DCPM_USE_LOCAL_PACKAGES=ON \
-DCMAKE_PREFIX_PATH=/PATH/TO/PREFIX
cmake --build build/parser --config Release
cmake --install build/parser --config Release --prefix /PATH/TO/PREFIX

cmake -S . -B build/release -DCMAKE_BUILD_TYPE=Release \
-DBUILD_TESTING=OFF -DBUILD_DOCS=OFF -DCEL_INSTALL=ON
-DBUILD_TESTING=OFF -DBUILD_DOCS=OFF -DCPM_USE_LOCAL_PACKAGES=ON \
-DCMAKE_PREFIX_PATH=/PATH/TO/PREFIX
cmake --build build/release --config Release
cmake --install build/release --config Release --prefix /PATH/TO/PREFIX
```

Replace `/PATH/TO/PREFIX` with your installation prefix. This installs the
standard library and its parser/runtime dependencies.
Replace `/PATH/TO/cel-runtime` and `/PATH/TO/cel-parser` with the respective
source directories, and `/PATH/TO/PREFIX` with your installation prefix.
Each install command installs only that library, not its dependencies.

In the consuming project, find the package and link its exported target:

Expand Down
70 changes: 0 additions & 70 deletions tests/consumer.cmake.in

This file was deleted.

14 changes: 0 additions & 14 deletions tests/consumer/CMakeLists.txt

This file was deleted.

19 changes: 0 additions & 19 deletions tests/consumer/main.cpp

This file was deleted.

Loading