Releases: open-telemetry/opentelemetry-cpp
OpenTelemetry C++ v1.8.2
v1.8.2 release
Release of core packages
- opentelemetry-api
- opentelemetry-sdk
and exporter packages:
- opentelemetry-exporter-otlp (gRPC + HTTP/JSON)
- opentelemetry-exporter-etw
API
- No API change
SDK
Exporter
- Fix console debug logs for otlp exporters. by @marcalff in #1848
- Enable setting Span endtime for ETW exporter by @lalitb in #1846
- [ETW Exporter] Add Virtual destructor for TailSampler, Update Maintainer mode warnings for MSVC by @lalitb in #1897
Build
- Fix OTELCPP_MAINTAINER_MODE by @marcalff in #1844
- Fix #1856 by @lalitb in #1857
- Fix typo in packages.cmake causing incorrect nuget package versions by @bretdusseault in #1936
- Cleanup CMake makefiles for CURL usage by @marcalff in #1916
- Migrate from @bazel_tools//platforms to https://github.com/bazelbuild/platforms by @davidmandle in #1873
- Enable generating deb, rpm, NuGet, tgz, zip package through cmake build by @lalitb in #1662
- Cleanup CMake makefiles for nlohmann_json. by @marcalff in #1912
- Fix compatibility when using clang and libc++ by @owent in #1852
- fix SpinLockMutex for Intel Compiler by @gabswb in #1885
- sdk::resource::Resource::Merge should be const by @esigo in #1905
Metrics
- Custom Aggregation support by @lalitb in #1899
- Fix warning for misconfiguration of PeriodicExportingMetricReader by @jwbuurlage in #1929
- Make macros.h available for all source files via version.h by @ThomsonTan in #1918
- minor metrics handling optimizations by @ays7 in #1890
- Collect and Export metric data before PeriodicMetricReader shutdown. by @lalitb in #1860
- Histogram Aggregation: Fix bucket detection logic, performance improvements, and benchmark tests by @lalitb in #1869
- Update meter.h by @sanjaypujare in #1907
Logs
- Update logs sdk and api to follow specification by @owent in #1884
- New
LogRecord
andRecordable
implementations. by @owent in #1766 - Change BatchLogRecordProcessorFactory::Create to static method by @ninghejun in #1876
- Fix resource and scope of new Logs SDK implementation. by @owent in #1881
Sementic Convention
Documentation
- Updated clone command in INSTALL.md by @paul-ohl in #1818
- [MAINTAINER DOC] Define and document a deprecation process by @marcalff in #1923
- Small fix in INSTALL.md for enabling building package. by @lalitb in #1930
Examples
Removal
- Remove deprecated experimental semantic conventions (#1741) by @marcalff in #1743
- Remove redundant macro check in nostd::shared_ptr by @ThomsonTan in #1939
- Small cleanup to remove old metrics design docs by @lalitb in #1855
- Remove unused namespace alias for nostd by @ThomsonTan in #1914
New Contributors
- @paul-ohl made their first contribution in #1818
- @ninghejun made their first contribution in #1876
- @gabswb made their first contribution in #1885
- @johanpel made their first contribution in #1871
- @sanjaypujare made their first contribution in #1907
- @jwbuurlage made their first contribution in #1929
- @bretdusseault made their first contribution in #1936
Full Changelog: v1.8.1...v1.8.2
Notes:
Deprecation notes:
- [MAINTAINER DOC] Define and document a deprecation process,
#1923- A new file, DEPRECATED list all the code currently
deprecated. - A new deprecation process details the plan to
deprecate and later remove code.
- A new file, DEPRECATED list all the code currently
- [DEPRECATION] Deprecate the Jaeger exporter
#1923- The Jaeger Exporter is deprecated, see DEPRECATED for details.
Important changes:
- [BUILD] Cleanup CMake makefiles for CURL usage
#1916- CMake option
WITH_OTLP_HTTP
- Before this change, the CMake option
WITH_OTLP_HTTP
was unpredictable,
sometime set to ON and sometime set to OFF by default,
depending on whether a CURL package was found or not.
The optionWITH_OTLP_HTTP
was sometime not displayed in the ccmake
UI, making it impossible to even discover there is an option of that name. - With this change, CMake option
WITH_OTLP_HTTP
is always OFF by
default. WITH_OTLP_HTTP MUST be set to ON explicitly to build the
OTLP HTTP exporter. The option is always visible in the ccmake UI.
- Before this change, the CMake option
- CMake option
BUILD_W3CTRACECONTEXT_TEST
- Before this change, the W3C trace context tests were built, or
not, in an unpredictable way, depending on the presence, or not, of a
CURL package. In particular, the build could ignore the W3C trace
context tests even when BUILD_W3CTRACECONTEXT_TEST=ON. - With this change, option BUILD_W3CTRACECONTEXT_TEST is honored.
- Before this change, the W3C trace context tests were built, or
- HTTP client/server examples
- Before this change, the HTTP client/server examples were built, or
not, in an unpredictable way, depending on the presence, or not, of a
CURL package. - With this change, a new option
WITH_EXAMPLES_HTTP
is used to
build the HTTP client/server examples.
- Before this change, the HTTP client/server examples were built, or
- CMake option
OpenTelemetry C++ v1.8.1
v1.8.1 release
Release of core packages
- opentelemetry-api
- opentelemetry-sdk
and exporter packages:
- opentelemetry-exporter-otlp (gRPC)
- opentelemetry-exporter-etw
- opentelemetry-exporter-prometheus
API
- No API change
SDK
Exporter
- [ETW Exporter] Tail based sampling support by @lalitb in #1780
- fix
enum-compare-switch
warning by @flier in #1833
Build
- [BUILD] move client::nosend under test_common by @esigo in #1811
- [BUILD] Fix default bazel build by @esigo in #1816
- Fix Prometheus target name by @lalitb in #1820
- Fix opentelemetry-proto file exists check by @eguzki in #1824
- Moved otlp_grpc_utils.cc to opentelemetry_exporter_otlp_grpc_client. by @lalitb in #1829
Metrics
- Change default temporality as "Cumulative" for OTLP metrics exporters by @lalitb in #1828
- fix typo [affecting otlp exported histogram metrics max] by @ays7 in #1827
Logs
- No Logs change
Sementic Convention
- No Sementic Convention change
Documentation
- No Documentation change
Others
- Fix type mismatch when move
nostd::shared_ptr
by @owent in #1815 - Clean unused docker files by @esigo in #1817
New Contributors
Full Changelog: v1.8.0...v1.8.1
OpenTelemetry C++ v1.8.0
v1.8.0 release
Release of core packages
- opentelemetry-api
- opentelemetry-sdk
and exporter packages:
- opentelemetry-exporter-otlp (gRPC + HTTP/JSON)
- opentelemetry-exporter-etw
- opentelemetry-exporter-prometheus
API
- No API change
SDK
Exporter
- [ETW Exporter] Fix span timestamp(s) precision to nanoseconds by @lalitb in #1726
- [Prometheus Exporter] add fix for prometheus exporter build by @rochaudhari in #1795
- Fix session lock of
OtlpHttpClient
by @owent in #1760 - Add status code to OTLP grpc trace log by @ThomsonTan in #1792
Build
- Multiple CURL packages leads to invalid build (#1738) by @marcalff in #1739
- Bring your own dependency: opentelemetry-proto by @marcalff in #1730
- bump to gRPC v1.48.1 for bazel CIs by @esigo in #1786
- Fix clang-format in CI by @marcalff in #1796
- Fix CI build by @marcalff in #1798
- Fix CI benchmark by @marcalff in #1799
- Add option WITH_BENCHMARK to disable building benchmarks by @ThomsonTan in #1794
- Upgrade bazel build to use abseil-cpp-20220623.1 by @marcalff in #1779
- Fix benchmark CI by @esigo in #1808
- Bump abseil-cpp for cmake CI by @esigo in #1807
Metrics
- Remove old metric from GitHub CI by @lalitb in #1733
- Cleanup of old _metric api/sdk by @esigo in #1734
- Cleanup ENABLE_METRICS_PREVIEW by @esigo in #1735
- Change Prometheus CMake target name by @lalitb in #1765
- Add MeterContext::ForEachMeter() method to process callbacks on Meter in thread-safe manner by @lalitb in #1783
Logs
- LogProcessor, LogExporter changes by @owent in #1727
- LogProcessor, LogExporter class name by @esigo in #1736
Sementic Convention
- [SEMANTIC CONVENTIONS] Upgrade to version 1.15.0 by @marcalff in #1761
- [Deprecation] Deprecate experimental semantic conventions (#1742) by @marcalff in #1744
Documentation
- Update Metrics status in README.md by @lalitb in #1722
- Remove misleading comments about ABI compatibility for nostd::span by @marcalff in #1731
- Cleanup ENABLE_METRICS_PREVIEW by @marcalff in #1745
- Format config options in OTLP exporter readme by @ThomsonTan in #1748
- Cleanup INSTALL.md by @ThomsonTan in #1757
- Document that clang-format version 10.0 is used. by @marcalff in #1782
New Contributors
- @rochaudhari made their first contribution in #1795
Full Changelog: v1.7.0...v1.8.0
Notes:
Deprecation notes:
- [Deprecation] Deprecate experimental semantic conventions
#1744-
The file
api/include/opentelemetry/trace/experimental_semantic_conventions.h
is deprecated, and will be removed in a future release.
Use file
api/include/opentelemetry/trace/semantic_conventions.h
instead. -
The file
sdk/include/opentelemetry/sdk/resource/experimental_semantic_conventions.h
is deprecated, and will be removed in a future release.
Use file
sdk/include/opentelemetry/sdk/resource/semantic_conventions.h
instead. -
The function, declared in the global namespace
uint32_t hashCode(const char *str, uint32_t h = 0)
is deprecated, and will be removed in a future release.
No replacement will be provided.
Note that functionopentelemetry::utils::hashCode
,
declared in the ETW exporter, is not affected by this deprecation.
-
Breaking changes:
- [SEMANTIC CONVENTIONS] Upgrade to version 1.15.0
#1761- Naming of semantic conventions has changed from uppercase constants,
likeSemanticConventions::SERVICE_NAME
,
to camel case, likeSemanticConventions::kServiceName
.
This is necessary to avoid collisions with macros in general,
which breaks the build on some platforms. - Semantic conventions are flagged as experimental,
which is why this change is done in this release.
- Naming of semantic conventions has changed from uppercase constants,
- [METRICS] Old metrics implementation including API, SDK and Exporters removed.
OpenTelemetry C++ v1.7.0 (Metrics API/SDK GA)
v1.7.0 release
Release of core packages
- opentelemetry-api
- opentelemetry-sdk
and exporter packages:
- opentelemetry-exporter-otlp (gRPC + HTTP/JSON)
- opentelemetry-exporter-es
Changelog
API
- No API change
SDK
- No SDK change
Exporter
- Add user agent for OTLP http/grpc client by @owent in #1657
- Fix debug log of OTLP HTTP exporter and ES log exporter by @owent in #1703
Build
- Bump gRPC to v1.48.1 for CMake Linux CI by @esigo in #1608
- Bump vcpk to 2022.08.15 by @esigo in #1633
- Fix more clang and gcc warnings by @marcalff in #1658
- Detect ARCH=sparc in CMake by @marcalff in #1660
- Fixed many remaining compiler warnings by @marcalff in #1677
- Add CMake OTELCPP_MAINTAINER_MODE by @marcalff in #1650
- Add e2e test to asan & tsan CI by @esigo in #1670
- Add otlp-grpc example bazel by @esigo in #1708
Metrics
- Fix #1632 - Occasional Segfault with LongCounter instrument by @lalitb in #1638
- [Metrics SDK] Change boundry type to
double
for Explicit Bucket Histogram Aggregation, and change default bucket range by @lalitb in #1626 - Fix #1588 - Observable Gauge does not reflect updated values, and send the old value always by @lalitb in #1641
- [Metrics SDK] Add Metrics ExemplarFilter and ExemplarReservoir by @esigo in #1584
- Fix observable Gauge metrics generation by @lalitb in #1651
- Fix data race on MeterContext::meters_ by @esigo in #1668
- Fix #1663 Threading issue between Meter::RegisterSyncMetricStorage and Meter::Collect by @lalitb in #1666
- Add timeout support to MeterContext::ForceFlush by @ThomsonTan in #1673
- Fix:1676 Segfault when short export period is used for metrics by @lalitb in #1682
- Fix Histogram crash by @esigo in #1685
- Fix a potential precision loss on integer in ReservoirCellIndexFor by @ThomsonTan in #1696
- [Metrics SDK] Add support for Pull Metric Reader by @esigo in #1701
- [Metrics API/SDK] Switch to explicit 64 bit integers by @esigo in #1686
- [Metrics API/SDK] Change Meter API/SDK to return nostd::unique_ptr for Sync Instruments by @esigo in #1707
- [Metrics SDK] Move Metrics Exemplar processing behind feature flag by @lalitb in #1710
- Fix:1674, Add Monotonic Property to Sum Aggregation, and unit tests for Up Down Counter by @lalitb in #1675
- Fix: 1712 - Validate Instrument meta data (name, unit, description) by @lalitb in #1713
Logs
Sementic Convention
Documentation
- Fix typo in package name in documentation. by @davidmandle in #1636
- Fix some typo in CHANGELOG by @ThomsonTan in #1637
- Fix:#1575 API Documentation for Metrics SDK and API by @lalitb in #1678
- [DOCS] - Minor updates to OStream Metrics exporter documentation by @lalitb in #1679
- Document libthrift 0.12.0 doesn't work with Jaeger exporter by @ThomsonTan in #1714
New Contributors
- @davidmandle made their first contribution in #1636
Full Changelog: v1.6.1...v1.7.0
Notes:
Metrics API/SDK GA release includes PRs #1686, #1701 and #1707 with breaking changes in the Metrics API and SDK.
OpenTelemetry C++ v1.6.1
v1.6.1 release
Release of core packages
- opentelemetry-api
- opentelemetry-sdk
and exporter packages:
- opentelemetry-exporter-otlp (gRPC + HTTP/JSON)
- opentelemetry-exporter-etw
- opentelemetry-exporter-zipkin
- opentelemetry-exporter-jaeger (thrift + UDP/HTTP)
Changelog
API
- No API change
SDK
- Upgrade opentelemetry-proto to v0.19.0 by @lalitb in #1579
- Add error log when getting a http error code by @owent in #1581
- Fix ObservableInstrument::RemoveCallback by @ahadnagy in #1582
- Fix
LoggerContext::Shutdown
and tsan ofOtlpHttpClient
by @owent in #1592 - Fix header only api singletons (#1520) by @marcalff in #1604
- resource sdk: Update Resource::Merge function docs by @ricekot in #1615
- [gRPC]: Fix oob access of string_view in example by @Tradias in #1619
- Fixes span creation benchmark issue #1612. by @marcalff in #1622
Exporter
- ETW Exporter - Add support for Sampler and ID Generator by @lalitb in #1547
- ETW Exporter - Add Trace flags in SpanContext by @lalitb in #1618
Build
- codecov ignore paths by @esigo in #1609
- Fix build warnings by @marcalff in #1613
- Fix more build warnings (#1616) by @marcalff in #1620
Metrics
- Update metrics status to Release Candidate by @lalitb in #1570
- Metrics warnings by @esigo in #1583
- Fix 1585 - Multiple cumulative metric collections without measurement recording. by @lalitb in #1586
- Fix default value of
OtlpHttpMetricExporterOptions::aggregation_temporality
. by @owent in #1601 - Add Histogram tests for Synchronous Metric Storage. by @lalitb in #1597
- Add OTLP Metric Exporter Factory and
OtlpGrpcClient
by @owent in #1606 - Example for OTLP gRPC exporter for Metrics. by @lalitb in #1598
Sementic Convention
New Contributors
Full Changelog: v1.6.0...v1.6.1
Notes:
While OpenTelemetry semantic convention is still in experimental state, PR #1624 upgraded it from 1.12.0 to 1.13.0 which MAY break the instrumentation library. Please update the semantic convention in instrumentation library is needed.
OpenTelemetry C++ v1.6.0 (Metrics release candidate)
v1.6.0 release (Metrics release candidate)
Release of core packages
- opentelemetry-api
- opentelemetry-sdk
and exporter packages:
- opentelemetry-exporter-otlp (gRPC + HTTP/JSON)
- opentelemetry-exporter-etw
- opentelemetry-exporter-zipkin
- opentelemetry-exporter-jaeger (thrift + UDP/HTTP)
Changelog
API
- No API change
SDK
- Fix log sdk builder (#1486) by @marcalff in #1524
- [Trace] Add SpanData getter for Span Recordable by @lalitb in #1508
- Fix infinitely waiting when shutdown with more than one running http sessions. by @owent in #1549
Exporter
- Prometheus exporter support Gauge Type by @esigo in #1553
- [NFC] Improve scope/instrument names in metrics OStream exporter by @bsarden in #1544
Build
- vscode debug launch.json by @esigo in #1537
- Fix several compiling/linking errors by @owent in #1539
- Fix code scanning alert by @esigo in #1530
- Add CI jobs for new and deprecated metrics by @esigo in #1531
Test
Metrics Features
- Add configuration options for Aggregation creation by @esigo in #1513
- Support multiple async callbacks by @lalitb in #1495
- OStream exporter should print out resource attributes by @bsarden in #1523
- Histogram min/max support by @esigo in #1540
- Metric aggregation temporality controls by @lalitb in #1541
- Fix OTLP gRPC Metrics env variables by @lalitb in #1543
- Fix default Metric view name by @esigo in #1515
- Fix IWYU error in instruments.h by @bsarden in #1555
- Fix metrics context circular reference by @esigo in #1535
- fix metrics race condition by @esigo in #1552
- remove throw check from metrics with noexcept by @esigo in #1560
- Fix metrics asan and tsan CI by @esigo in #1562
- Calling Observable Instruments callback during metrics collection by @lalitb in #1554
New Contributors
Full Changelog: v1.5.0...v1.6.0
OpenTelemetry C++ v1.5.0
v1.5.0 release
Release of core packages
- opentelemetry-api
- opentelemetry-sdk
and exporter packages:
- opentelemetry-exporter-otlp (gRPC + HTTP/JSON)
- opentelemetry-exporter-etw
- opentelemetry-exporter-zipkin
- opentelemetry-exporter-jaeger (thrift + UDP/HTTP)
##Changelog
API
- No API change
SDK
- fix: urlPaser will incorrect parsing url like "http://abc.com/xxx@xxx/a/b" #1511
- Rename
InstrumentationLibrary
toInstrumentationScope
#1507 - Add automatically semantic conventions from the spec (#873) #1497
- Use template class for in-memory data. #1496
- fix compiler warnings #1499
- Add trace sdk builders (#1393) #1471
- Remove reference to deprecated InstrumentationLibrary in OTLP #1469
- Fix trace kIsSampled flag set incorrectly #1465
- Fix build warnings about missing aggregates. #1368
Exporter
- Add resources to dep list of prometheus exporter test #1527
- Inline print_value() in ostream exporter #1512
- fix otlp grpc exporter naming #1488
- Fix endpoint in otlp grpc exporter #1474
- fix prometheus exporter failure type #1460
Semantic Conventions
- Upgrade to version 1.12.0 #873
Build
- Don't require applications using jaeger exporter to know about libcurl #1518
- Try to build nlohmann-json only it's depended. #1505
- Remove
--config Debug
when installing. #1480
Docs
- Update docs to use relative code links. #1447
Example
Ext
curl::HttpClient
usecurl_multi_handle
instead of creating a thread for every request and it's able to reuse connections now. (#1317)
Metrics Features
OpenTelemetry C++ v1.4.1
v1.4.1 release
Release of core packages
- opentelemetry-api
- opentelemetry-sdk
and exporter packages:
- opentelemetry-exporter-otlp (gRPC + HTTP/JSON)
- opentelemetry-exporter-etw
- opentelemetry-exporter-zipkin
- opentelemetry-exporter-jaeger (thrift + UDP/HTTP)
Changelog
API
- No API change.
SDK
- fix: WaitOnSocket select error when sockfd above FD_SETSIZE (#1410)
- fix OTEL_INTERNAL_LOG_INFO (#1407)
Build
- Upgrade nlohmann_json to 3.10.5 (#1441)
- install sdk-config.h (#1419)
- fix nlohmann_json's (third party) include dir (#1415)
Example
- Log current timestamp instead of epoch time (#1434)
Docs
- Fixed broken link to OpenTelemetry.io (#1446)
- Fix GettingStarted documentation for Jaeger HTTP exporter (#1439)
- Document Getting Started with Prometheus and Grafana (#1396)
Metrics features
OpenTelemetry C++ v1.4.0
v1.4.0 release
Release of core packages
- opentelemetry-api
- opentelemetry-sdk
and exporter packages:
- opentelemetry-exporter-otlp (gRPC + HTTP/JSON)
- opentelemetry-exporter-etw
- opentelemetry-exporter-zipkin
- opentelemetry-exporter-jaeger (thrift + UDP/HTTP)
Changelog
API
- Upgrade proto to v0.17.0, update log data model (#1383)
- Add noexcept/const qualifier at missing places for Trace API. (#1374)
- Update yield logic for ARM processor (#1325)
SDK
- Get span_id from context when Logger::Log received invalid span_id (#1398)
- Fix sharing resource in batched exported spans (#1386)
- Fix empty tracestate header propagation (#1373)
- Fix baggage propagation for empty/invalid baggage context (#1367)
- Add explicit type cast in baggage UrlDecode (#1353)
Exporters
- Fix scalar delete against array (#1356)
- Conditional include for codecvt header (#1355)
- Prometheus exporter (#1331)
Build
- Alpine image (#1382)
- Fix missing link to nlohmann_json (#1390)
- Prometheus exporter meters and instrument name (#1378)
- Export opentelemetry_otlp_recordable (#1365)
- Add missing include guard (#1357)
- Use latest TraceLoggingDynamic.h (#1354)
- ostream metrics cmake (#1344)
- Link opentelemetry_ext with opentelemetry_api (#1336)
- Dependencies image as artifact (#1333)
- Fix Ninja path (#1326)
- Fix metrics compiler warnings (#1328)
Metrics features
- Connect async storage with async instruments (#1388)
- Reuse temporal metric storage for sync storage (#1369)
- Fix class member initialization order (#1360)
- Simplify SDK Configuration: Use View with default aggregation if no matching View is configured (#1358)
- Remove exporter registration to meter provider (#1350)
- Fix output time in metrics OStream exporter (#1346)
- Enable metric collection for Async Instruments - Delta and Cumulative (#1334)
- Metrics histogram example (#1330)
- Implement Merge and Diff operation for Histogram Aggregation (#1303)
Examples
- Prometheus example (#1332)
Docs
- Getting started document using ostream exporter (#1394)
Notes:
- This release includes alpha milestone of OpenTelemetry Metrics.
- The name parameter for Log APIs is deprecated and will be removed in future releases. See details in CHANGELOG.md
OpenTelemetry C++ v1.3.0
v1.3.0 release
Release of core packages
- opentelemetry-api
- opentelemetry-sdk
and exporter packages:
- opentelemetry-exporter-otlp (gRPC + HTTP/JSON)
- opentelemetry-exporter-etw
- opentelemetry-exporter-zipkin
- opentelemetry-exporter-jaeger (thrift + UDP/HTTP)
Changelog
API
- Allow extension of the lifetime of ContextStorage. (#1214)
SDK
- Bugfix: span SetAttribute crash (#1283)
- Reorder the destructor of members in LoggerProvider and TracerProvider (#1245)
Exporters
- ETW provider handle cleanup (#1322)
- Fix: use CURLOPT_TIMEOUT_MS to config OtlpHttpExporter's timeout instead of CURLOPT_TIMEOUT (#1261)
- Jaeger Exporter - Populate Span Links (#1251)
Build
- Move public definitions into
opentelemetry_api
. (#1314) - Rename
http_client_curl
toopentelemetry_http_client_curl
(#1301) - Update grpc to v1.43.2 to support VS2022/MSVC 19.30 and bazel 5.0 (#1207)
Experimental metrics features
- OStream example (#1312)
- Add InstrumentationInfo and Resource to the metrics data to be exported. (#1299)
- Implement periodic exporting metric reader (#1286)
- Synchronous Metric collection (Delta , Cumulative) (#1265)
- Metrics exemplar round 1 (#1264)
- Enable metric collection from MetricReader (#1241)
- Asynchronous Aggregation storage (#1232)
- Synchronous Instruments - Aggregation Storage(s) creation for configured views (#1219)
- Add Aggregation storage (#1213)
- Ostream metric exporter (#1196)
- Filtering metrics attributes (#1191)
- Sync and Async Instruments SDK (#1184)
- Add Aggregation as part of metrics SDK. (#1178)
Notes:
#1301 added opentelemetry_
as prefix to http_client_curl library for resolving potential naming conflict, this could break existing cmake build if http_client_curl is listed as explicit dependency in user's cmake file.