UNIXworkcode

1 # Build Instructions 2 3 The build processes uses configure and make. 4 Make sure that you have `make` and a 5 <tooltip term="supported-compilers">supported compiler</tooltip> 6 installed. 7 8 <tabs> 9 <tab title="Unix / Linux"> 10 <procedure> 11 <step> 12 Download the latest source archive from 13 <a href="https://sourceforge.net/projects/ucx/files/">Source Forge</a> and extract it somewhere on your machine. 14 You can also use the command line to do this. 15 <code-block lang="shell"> 16 wget -O libucx.tgz https://sourceforge.net/projects/ucx/files/latest 17 tar -xzf libucx.tgz 18 cd libucx 19 </code-block> 20 </step> 21 <step> 22 Configure the build according to your preferences. You can get a list of 23 all available options with <code>./configure --help</code>. 24 The recommended configuration for production builds is <code>./configure --release</code>. 25 <code-block lang="shell"> 26 ./configure --release 27 make 28 make check 29 sudo make install 30 </code-block> 31 <note>The check target is optional and only runs some tests with the built software.</note> 32 </step> 33 </procedure> 34 </tab> 35 <tab title="Windows"> 36 <procedure> 37 <step> 38 Download the latest source archive from 39 <a href="https://sourceforge.net/projects/ucx/files/">Source Forge</a> and extract it somewhere on your machine. 40 </step> 41 <step> 42 Navigate to the folder named <code>msvc</code> in the extracted directory structure. 43 </step> 44 <step> 45 Open the contained <code>ucx.sln</code> in Visual Studio and build the solution. 46 </step> 47 <step> 48 The libucx project in the solution will produce a libucx.lib that can be used for static linking 49 and the libucx_dll project will produce a libucx.dll and a libucx.dll.lib import lib for dynamic linking. 50 </step> 51 </procedure> 52 <note> 53 For native Windows projects it is recommended to statically link UCX. 54 </note> 55 </tab> 56 </tabs> 57 58 ## Compile Time Options 59 60 When compiling UCX, you can tweak several compile time variables via macro definitions. 61 62 ### Features Defines 63 64 The following macros are not defined by default. 65 The effect when they are defined is described in the table. 66 67 <table> 68 <tr> 69 <th>Macro</th> 70 <th>Effect</th> 71 </tr> 72 <tr> 73 <td>CX_NO_SZMUL_BUILTINT</td> 74 <td> 75 By default, UCX uses a compiler builtin (only available for clang and gcc) 76 to perform multiplications with overflow check. 77 When this macro is defined, using the builtin is disabled and UCX will 78 always use an own implementation. 79 <tip> 80 This macro is defined when you use the <code>--disable-szmul-builtin</code> 81 option during configuration, so you do not need to define it manually. 82 </tip> 83 </td> 84 </tr> 85 <tr> 86 <td>CX_WINDLL</td> 87 <td> 88 Define this macro during compilation of the project that is <emphasis>using</emphasis> 89 UCX as a Windows DLL to import the symbols. 90 In general it is recommended to use UCX as a static library under Windows, though. 91 </td> 92 </tr> 93 <tr> 94 <td>CX_WINDLL_EXPORT</td> 95 <td> 96 Define this macro during compilation of UCX to export symbols for a Windows DLL. 97 <tip>The Visual Studio Solution does that automatically.</tip> 98 </td> 99 </tr> 100 </table> 101 102 ### Small Buffer Optimizations 103 104 With the following macros you can control the size of stack memory for small buffer optimizations. 105 106 <table> 107 <tr> 108 <th>Macro</th> 109 <th>Description</th> 110 <th>Default</th> 111 </tr> 112 <tr> 113 <td>CX_ARRAY_SWAP_SBO_SIZE</td> 114 <td>The maximum size of an element in an array list that can be swapped without allocating heap memory.</td> 115 <td>128</td> 116 </tr> 117 <tr> 118 <td>CX_LINKED_LIST_SORT_SBO_SIZE</td> 119 <td>The maximum list size that uses SBO during sort (memory required is this value multiplied by the size of a pointer).</td> 120 <td>1,024</td> 121 </tr> 122 <tr> 123 <td>CX_PRINTF_SBO_SIZE</td> 124 <td>The maximum string length functions in printf.h use stack memory for.</td> 125 <td>512</td> 126 </tr> 127 <tr> 128 <td>CX_STRSTR_SBO_SIZE</td> 129 <td>The maximum length of the "needle" in cx_strstr that can use SBO.</td> 130 <td>128</td> 131 </tr> 132 </table> 133 134 135 ### Other Buffers 136 137 With the following macros you can control other buffer sizes that are not falling into the category of small buffer optimizations. 138 139 <table> 140 <tr> 141 <th>Macro</th> 142 <th>Description</th> 143 <th>Default</th> 144 </tr> 145 <tr> 146 <td>CX_STRREPLACE_INDEX_BUFFER_SIZE</td> 147 <td> 148 The number of matches the index buffer can store on the stack. 149 If the function finds more matches, more index buffers of the same size are allocated on the heap. 150 </td> 151 <td>64</td> 152 </tr> 153 <tr> 154 <td>CX_STREAM_COPY_BUF_SIZE</td> 155 <td>The buffer size on the stack for a stream copy.</td> 156 <td>1,024</td> 157 </tr> 158 <tr> 159 <td>CX_STREAM_BCOPY_BUF_SIZE</td> 160 <td>The buffer size on the heap for a stream copy.</td> 161 <td>8,192</td> 162 </tr> 163 <tr> 164 <td>CX_PROPERTIES_LOAD_FILL_SIZE</td> 165 <td>The size of the stack buffer used to fill the parser in cxPropertiesLoad().</td> 166 <td>1,024</td> 167 </tr> 168 <tr> 169 <td>CX_PROPERTIES_LOAD_BUF_SIZE</td> 170 <td>The size of the stack used for the line buffer in cxPropertiesLoad().</td> 171 <td>256</td> 172 </tr> 173 </table> 174