docs/Writerside/topics/install.md

# Build Instructions

The build processes uses configure and make.
Make sure that you have `make` and a
<tooltip term="supported-compilers">supported compiler</tooltip>
installed.

<tabs>
<tab title="Unix / Linux">
<procedure>
<step>
Download the latest source archive from
<a href="https://sourceforge.net/projects/ucx/files/">Source Forge</a> and extract it somewhere on your machine.
You can also use the command line to do this. 
<code-block lang="shell">
wget -O libucx.tgz https://sourceforge.net/projects/ucx/files/latest
tar -xzf libucx.tgz
cd libucx
</code-block>
</step>
<step>
Configure the build according to your preferences. You can get a list of
all available options with <code>./configure --help</code>.
The recommended configuration for production builds is <code>./configure --release</code>.
<code-block lang="shell">
    ./configure --release
    make
    make check 
    sudo make install
</code-block>
<note>The check target is optional and only runs some tests with the built software.</note>
</step>
</procedure>
</tab>
<tab title="Windows">
<procedure>
<step>
Download the latest source archive from
<a href="https://sourceforge.net/projects/ucx/files/">Source Forge</a> and extract it somewhere on your machine.
</step>
<step>
Navigate to the folder named <code>msvc</code> in the extracted directory structure.
</step>
<step>
Open the contained <code>ucx.sln</code> in Visual Studio and build the solution.
</step>
<step>
The libucx project in the solution will produce a libucx.lib that can be used for static linking
and the libucx_dll project will produce a libucx.dll and a libucx.dll.lib import lib for dynamic linking.
</step>
</procedure>
<note>
For native Windows projects it is recommended to statically link UCX.
</note>
</tab>
</tabs>

## Using UCX

You can use UCX by either statically or dynamically linking the library.
With standard file extensions, the static library is `libucx.a` and the dynamic library is `libucx.so`.
In system-wide installations you usually only need to pass `-lucx` to the linker.
But to be sure, it is also possible to use `pkgconf` to determine the exact flags.

### Microsoft Windows Specific

You need to define the `CX_WINDLL` macro during compilation of the project that is using
UCX as a Windows DLL to import the symbols.
In general, it is recommended to use UCX as a static library under Windows, though.

## Compile Time Options

When compiling UCX (not the program that is *using* UCX),
you can tweak several compile time variables via macro definitions.

### Features Defines

The following macros are not defined by default.
The effect when they are defined is described in the table.

<table>
<tr>
<th>Macro</th>
<th>Effect</th>
</tr>
<tr>
    <td>CX_NO_SZMUL_BUILTINT</td>
    <td>
        By default, UCX uses a compiler builtin (only available for clang and gcc)
        to perform multiplications with overflow check.
        When this macro is defined, using the builtin is disabled and UCX will
        always use an own implementation.
        <tip>
            This macro is defined when you use the <code>--disable-szmul-builtin</code>
            option during configuration, so you do not need to define it manually.
        </tip>
    </td>
</tr>
<tr>
    <td>CX_WINDLL_EXPORT</td>
    <td>
        Define this macro during compilation of UCX to export symbols for a Windows DLL.
        <tip>The Visual Studio Solution does that automatically.</tip>
    </td>
</tr>
</table>

### Small Buffer Optimizations

With the following macros you can control the size of stack memory for small buffer optimizations.

<table>
<tr>
<th>Macro</th>
<th>Description</th>
<th>Default</th>
</tr>
<tr>
    <td>CX_ARRAY_SWAP_SBO_SIZE</td>
    <td>The maximum size of an element in an array list that can be swapped without allocating heap memory.</td>
    <td>128</td>
</tr>
<tr>
    <td>CX_LINKED_LIST_SORT_SBO_SIZE</td>
    <td>The maximum list size that uses SBO during sort (memory required is this value multiplied by the size of a pointer).</td>
    <td>1,024</td>
</tr>
<tr>
    <td>CX_PRINTF_SBO_SIZE</td>
    <td>The maximum string length functions in printf.h use stack memory for.</td>
    <td>512</td>
</tr>
<tr>
    <td>CX_STRSTR_SBO_SIZE</td>
    <td>The maximum length of the "needle" in cx_strstr that can use SBO.</td>
    <td>128</td>
</tr>
</table>


### Other Buffers

With the following macros you can control other buffer sizes that are not falling into the category of small buffer optimizations. 

<table>
<tr>
<th>Macro</th>
<th>Description</th>
<th>Default</th>
</tr>
<tr>
    <td>CX_STRREPLACE_INDEX_BUFFER_SIZE</td>
    <td>
        The number of matches the index buffer can store on the stack.
        If the function finds more matches, more index buffers of the same size are allocated on the heap.
    </td>
    <td>64</td>
</tr>
<tr>
    <td>CX_STREAM_COPY_BUF_SIZE</td>
    <td>The buffer size on the stack for a stream copy.</td>
    <td>1,024</td>
</tr>
<tr>
    <td>CX_STREAM_BCOPY_BUF_SIZE</td>
    <td>The buffer size on the heap for a stream copy.</td>
    <td>8,192</td>
</tr>
<tr>
    <td>CX_PROPERTIES_LOAD_FILL_SIZE</td>
    <td>The size of the stack buffer used to fill the parser in cxPropertiesLoad().</td>
    <td>1,024</td>
</tr>
<tr>
    <td>CX_PROPERTIES_LOAD_BUF_SIZE</td>
    <td>The size of the stack used for the line buffer in cxPropertiesLoad().</td>
    <td>256</td>
</tr>
</table>