docs/dependencies.md

<!--

Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.

-->

# Consuming the TsFile SDK

## Use an installation, not a source checkout

Native integrations should depend on an installed TsFile SDK. Use the
installation instructions for the TsFile package and platform you select. Do not
add a second TsFile installer, vendor the core library, or automatically download
and build a floating branch from an extras module.

The established packaging contract provides a library, development headers,
CMake package configuration, and pkg-config metadata beneath an installation
prefix. The following references describe the SDK at commit `6f38c703962a`:

- [TsFile packaging documentation](https://github.com/apache/tsfile/blob/6f38c703962ab6224b09fc299f94ad42e6af88a1/packaging/README.md)
- [Installed CMake consumer](https://github.com/apache/tsfile/blob/6f38c703962ab6224b09fc299f94ad42e6af88a1/cpp/cmake/tests/projects/InstalledConsumer/CMakeLists.txt)
- [pkg-config metadata](https://github.com/apache/tsfile/blob/6f38c703962ab6224b09fc299f94ad42e6af88a1/cpp/cmake/libtsfile.pc.in)

## Selecting installation components

| Installation family | Development requirements |
| --- | --- |
| APT | Runtime `tsfile` and development package `tsfile-dev`. |
| RPM | Runtime `tsfile` and development package `tsfile-devel`. |
| Homebrew | The installed Formula's prefix, including library and headers; development Formula `tsfile-dev` is keg-only. |
| Windows SDK ZIP | The extracted SDK root containing `bin`, `include`, and `lib`, matching the consumer's architecture and toolchain. |

`tsfile-tools` supplies the CLI where packaging separates it from the library;
it is not a substitute for development headers and link files. Availability and
installation commands are owned by the TsFile package distribution. Do not infer
support for additional platforms or architectures from this table.

## CMake and pkg-config

CMake-based integrations should use `find_package(TsFile CONFIG REQUIRED)` and
link their actual targets to `TsFile::tsfile`. Use `CMAKE_PREFIX_PATH` to select
a non-default SDK installation, or `TsFile_DIR` for the directory containing
`TsFileConfig.cmake`. Consume the exported include paths and dependencies rather
than reconstructing them in a custom `FindTsFile.cmake`.

For a Homebrew development installation, `brew --prefix tsfile-dev` identifies
the Formula-specific prefix. Do not hard-code `/opt/homebrew` or `/usr/local`.
On Windows, point the consumer at the extracted SDK root, not just its DLL.

Consumers using pkg-config can query `libtsfile`; configure `PKG_CONFIG_PATH`
when the installation is outside the normal search path. Runtime library
resolution is separate from build-time package discovery and must be documented
by the integration.

## Shared and static linkage

Choose linkage according to the host and distribution requirements. An installed
SDK may be shared or static; an existing binary package must not be assumed to
contain both variants. Verify the selected artifact, compiler and runtime ABI,
position-independent code requirements, and transitive dependencies as relevant.

If the required SDK variant is unavailable as a package, build and install it
into a separate prefix using the upstream instructions, then consume that prefix
normally. Do not silently switch to a network source build during configuration.

For shared builds, deployment instructions must account for the runtime library.
For static builds, preserve the exported dependency and licensing requirements.

## Source-based development

To work with an unpublished core change, the developer builds and installs TsFile
into a chosen prefix outside this repository. Extras then uses that same CMake
or pkg-config interface. SDK source location and build directories are not part
of the integration contract.

Installed headers include a compatibility closure, not only stable public entry
points. Consult the [public-header definition](https://github.com/apache/tsfile/blob/6f38c703962ab6224b09fc299f94ad42e6af88a1/cpp/cmake/TsFilePublicHeaders.cmake)
and document any dependence on implementation-level interfaces.

## Version records

Each implementation should record the following when it is actually exercised:

- Exact SDK artifact version, source commit when available, and distribution.
- Host system version, operating system, architecture, and relevant toolchain.
- Shared or static linkage and important SDK build options.
- Commands run, results, and known limitations.

Development snapshots must remain labeled as such; do not describe them as RCs
or formal releases. Pin immutable versions when reproducibility is needed rather
than relying on `latest` or a moving branch.