# Integrating and configuring PTL

<!-- Note to AI grammar checker: this document uses Posix in preference to POSIX. -->


<!-- TOC -->

- [Integration](#integration)
    - [CMake via FetchContent](#cmake-via-fetchcontent)
    - [Building and installing on your system](#building-and-installing-on-your-system)
        - [Basic use](#basic-use)
        - [CMake package](#cmake-package)
        - [Via pkg-config](#via-pkg-config)
    - [Copying to your sources](#copying-to-your-sources)
- [Configuration](#configuration)

<!-- /TOC -->

## Integration

### CMake via FetchContent

```cmake
include(FetchContent)
...
FetchContent_Declare(ptl
    GIT_REPOSITORY  https://github.com/gershnik/ptl.git
    GIT_TAG         v1.0  # use the tag, branch or sha you need
    GIT_SHALLOW     TRUE
)
...
FetchContent_MakeAvailable(ptl)
...
target_link_libraries(mytarget
PRIVATE
  ptl::ptl
)
```
> ℹ&#xFE0F; _[What is FetchContent?](https://cmake.org/cmake/help/latest/module/FetchContent.html)_

### Building and installing on your system

You can also build and install PTL on your system using CMake.

1. Download or clone this repository into SOME_PATH.
2. On the command line:
```bash
cd SOME_PATH
cmake -S . -B build 

#Optional
#cmake --build build
#cmake --build build --target run-tests

#install to /usr/local
sudo cmake --install build
#or for a different prefix
#cmake --install build --prefix /usr
```

Once PTL has been installed, it can be used in the following ways:

#### Basic use 

Set the include directory to `<prefix>/include` where `<prefix>` is the install prefix from above.

#### CMake package

```cmake
find_package(ptl)

target_link_libraries(mytarget
PRIVATE
  ptl::ptl
)
```

#### Via `pkg-config`

Add the output of `pkg-config --cflags ptl` to your compiler flags.

Note that the default installation prefix `/usr/local` might not be in the list of places your
`pkg-config` looks into. If so, you might need to do:
```bash
export PKG_CONFIG_PATH=/usr/local/share/pkgconfig
```
before running `pkg-config`.


### Copying to your sources

You can also simply download the [inc](inc) directory of this repository somewhere in your source tree and add it to your include path.

However, note that using this method, you will not have the `ptl/config.h` configuration header for your platform generated by CMake and will need to work around it. See [Configuration](#configuration) for details.

## Configuration

When used via CMake (either through `FetchContent` or by installing), PTL has a configuration header `ptl/config.h` generated that specifies which non-standard facilities are available on your platform. 

If you do not want to use CMake at all, you can either:
1. Provide this header yourself or
2. Define the `PTL_NO_CONFIG` macro for the compilation to prevent its inclusion.

In either case, you can use PTL without any configuration macros defined, but it will be limited to standard Posix functionality available everywhere.
You can set the configuration macros manually, if desired, to match your platform. See [`cmake/config.cmake`](../cmake/config.cmake) for available macros and their meanings.

At compile time, you can control whether PTL uses `std::format` or `fmt::format` via the `PTL_USE_STD_FORMAT` macro. 
If it is not defined, PTL headers will try to detect whether `std::format` is sufficiently supported and, if so, use it.
Otherwise, they will fall back on `fmt::format`. You can override automatic detection by defining `PTL_USE_STD_FORMAT` to
1 or 0 on the command line or in code before including PTL headers.

When using `fmt`, PTL will attempt to include `<fmt/format.h>` unless the `FMT_VERSION` macro, which is defined by `fmt`, is
already defined. Thus, if you are using `fmt` with custom headers not reachable via `<fmt/format.h>`, simply include
them before PTL headers.




