1 _ _ ____ _ 2 ___| | | | _ \| | 3 / __| | | | |_) | | 4 | (__| |_| | _ <| |___ 5 \___|\___/|_| \_\_____| 6 7 How To Compile 8 9Installing Binary Packages 10========================== 11 12 Lots of people download binary distributions of curl and libcurl. This 13 document does not describe how to install curl or libcurl using such a 14 binary package. This document describes how to compile, build and install 15 curl and libcurl from source code. 16 17Building from git 18================= 19 20 If you get your code off a git repository, see the GIT-INFO file in the 21 root directory for specific instructions on how to proceed. 22 23UNIX 24==== 25 A normal unix installation is made in three or four steps (after you've 26 unpacked the source archive): 27 28 ./configure 29 make 30 make test (optional) 31 make install 32 33 You probably need to be root when doing the last command. 34 35 If you have checked out the sources from the git repository, read the 36 GIT-INFO on how to proceed. 37 38 Get a full listing of all available configure options by invoking it like: 39 40 ./configure --help 41 42 If you want to install curl in a different file hierarchy than /usr/local, 43 you need to specify that already when running configure: 44 45 ./configure --prefix=/path/to/curl/tree 46 47 If you happen to have write permission in that directory, you can do 'make 48 install' without being root. An example of this would be to make a local 49 install in your own home directory: 50 51 ./configure --prefix=$HOME 52 make 53 make install 54 55 The configure script always tries to find a working SSL library unless 56 explicitly told not to. If you have OpenSSL installed in the default search 57 path for your compiler/linker, you don't need to do anything special. If 58 you have OpenSSL installed in /usr/local/ssl, you can run configure like: 59 60 ./configure --with-ssl 61 62 If you have OpenSSL installed somewhere else (for example, /opt/OpenSSL) 63 and you have pkg-config installed, set the pkg-config path first, like this: 64 65 env PKG_CONFIG_PATH=/opt/OpenSSL/lib/pkgconfig ./configure --with-ssl 66 67 Without pkg-config installed, use this: 68 69 ./configure --with-ssl=/opt/OpenSSL 70 71 If you insist on forcing a build without SSL support, even though you may 72 have OpenSSL installed in your system, you can run configure like this: 73 74 ./configure --without-ssl 75 76 If you have OpenSSL installed, but with the libraries in one place and the 77 header files somewhere else, you have to set the LDFLAGS and CPPFLAGS 78 environment variables prior to running configure. Something like this 79 should work: 80 81 (with the Bourne shell and its clones): 82 83 CPPFLAGS="-I/path/to/ssl/include" LDFLAGS="-L/path/to/ssl/lib" \ 84 ./configure 85 86 (with csh, tcsh and their clones): 87 88 env CPPFLAGS="-I/path/to/ssl/include" LDFLAGS="-L/path/to/ssl/lib" \ 89 ./configure 90 91 If you have shared SSL libs installed in a directory where your run-time 92 linker doesn't find them (which usually causes configure failures), you can 93 provide the -R option to ld on some operating systems to set a hard-coded 94 path to the run-time linker: 95 96 env LDFLAGS=-R/usr/local/ssl/lib ./configure --with-ssl 97 98 MORE OPTIONS 99 ------------ 100 101 To force configure to use the standard cc compiler if both cc and gcc are 102 present, run configure like 103 104 CC=cc ./configure 105 or 106 env CC=cc ./configure 107 108 To force a static library compile, disable the shared library creation 109 by running configure like: 110 111 ./configure --disable-shared 112 113 To tell the configure script to skip searching for thread-safe functions, 114 add an option like: 115 116 ./configure --disable-thread 117 118 If you're a curl developer and use gcc, you might want to enable more 119 debug options with the --enable-debug option. 120 121 curl can be built to use a whole range of libraries to provide various 122 useful services, and configure will try to auto-detect a decent 123 default. But if you want to alter it, you can select how to deal with 124 each individual library. 125 126 To build with GnuTLS for SSL/TLS, use both --without-ssl and 127 --with-gnutls. 128 129 To build with Cyassl for SSL/TLS, use both --without-ssl and 130 --with-cyassl. 131 132 To build with NSS for SSL/TLS, use both --without-ssl and --with-nss. 133 134 To build with PolarSSL for SSL/TLS, use both --without-ssl and 135 --with-polarssl. 136 137 To build with axTLS for SSL/TLS, use both --without-ssl and --with-axtls. 138 139 To get GSSAPI support, build with --with-gssapi and have the MIT or 140 Heimdal Kerberos 5 packages installed. 141 142 To get support for SCP and SFTP, build with --with-libssh2 and have 143 libssh2 0.16 or later installed. 144 145 To get Metalink support, build with --with-libmetalink and have the 146 libmetalink packages installed. 147 148 SPECIAL CASES 149 ------------- 150 Some versions of uClibc require configuring with CPPFLAGS=-D_GNU_SOURCE=1 151 to get correct large file support. 152 153 The Open Watcom C compiler on Linux requires configuring with the variables: 154 155 ./configure CC=owcc AR="$WATCOM/binl/wlib" AR_FLAGS=-q \ 156 RANLIB=/bin/true STRIP="$WATCOM/binl/wstrip" CFLAGS=-Wextra 157 158 159Win32 160===== 161 162 Building Windows DLLs and C run-time (CRT) linkage issues 163 --------------------------------------------------------- 164 165 As a general rule, building a DLL with static CRT linkage is highly 166 discouraged, and intermixing CRTs in the same app is something to 167 avoid at any cost. 168 169 Reading and comprehension of Microsoft Knowledge Base articles 170 KB94248 and KB140584 is a must for any Windows developer. Especially 171 important is full understanding if you are not going to follow the 172 advice given above. 173 174 KB94248 - How To Use the C Run-Time 175 http://support.microsoft.com/kb/94248/en-us 176 177 KB140584 - How to link with the correct C Run-Time (CRT) library 178 http://support.microsoft.com/kb/140584/en-us 179 180 KB190799 - Potential Errors Passing CRT Objects Across DLL Boundaries 181 http://msdn.microsoft.com/en-us/library/ms235460 182 183 If your app is misbehaving in some strange way, or it is suffering 184 from memory corruption, before asking for further help, please try 185 first to rebuild every single library your app uses as well as your 186 app using the debug multithreaded dynamic C runtime. 187 188 If you get linkage errors read section 5.7 of the FAQ document. 189 190 191 MingW32 192 ------- 193 194 Make sure that MinGW32's bin dir is in the search path, for example: 195 196 set PATH=c:\mingw32\bin;%PATH% 197 198 then run 'mingw32-make mingw32' in the root dir. There are other 199 make targets available to build libcurl with more features, use: 200 'mingw32-make mingw32-zlib' to build with Zlib support; 201 'mingw32-make mingw32-ssl-zlib' to build with SSL and Zlib enabled; 202 'mingw32-make mingw32-ssh2-ssl-zlib' to build with SSH2, SSL, Zlib; 203 'mingw32-make mingw32-ssh2-ssl-sspi-zlib' to build with SSH2, SSL, Zlib 204 and SSPI support. 205 206 If you have any problems linking libraries or finding header files, be sure 207 to verify that the provided "Makefile.m32" files use the proper paths, and 208 adjust as necessary. It is also possible to override these paths with 209 environment variables, for example: 210 211 set ZLIB_PATH=c:\zlib-1.2.8 212 set OPENSSL_PATH=c:\openssl-0.9.8y 213 set LIBSSH2_PATH=c:\libssh2-1.4.3 214 215 ATTENTION: if you want to build with libssh2 support you have to use latest 216 version 0.17 - previous versions will NOT work with 7.17.0 and later! 217 Use 'mingw32-make mingw32-ssh2-ssl-zlib' to build with SSH2 and SSL enabled. 218 219 It is now also possible to build with other LDAP SDKs than MS LDAP; 220 currently it is possible to build with native Win32 OpenLDAP, or with the 221 Novell CLDAP SDK. If you want to use these you need to set these vars: 222 223 set LDAP_SDK=c:\openldap 224 set USE_LDAP_OPENLDAP=1 225 226 or for using the Novell SDK: 227 228 set USE_LDAP_NOVELL=1 229 230 If you want to enable LDAPS support then set LDAPS=1. 231 232 - optional MingW32-built OpenLDAP SDK available from: 233 http://www.gknw.net/mirror/openldap/ 234 - optional recent Novell CLDAP SDK available from: 235 http://developer.novell.com/ndk/cldap.htm 236 237 238 Cygwin 239 ------ 240 241 Almost identical to the unix installation. Run the configure script in the 242 curl root with 'sh configure'. Make sure you have the sh executable in 243 /bin/ or you'll see the configure fail toward the end. 244 245 Run 'make' 246 247 Dev-Cpp 248 ------- 249 250 See the separate INSTALL.devcpp file for details. 251 252 MSVC 6 caveats 253 -------------- 254 255 If you use MSVC 6 it is required that you use the February 2003 edition PSDK: 256 http://www.microsoft.com/msdownload/platformsdk/sdkupdate/psdk-full.htm 257 258 Building any software with MSVC 6 without having PSDK installed is just 259 asking for trouble down the road once you have released it, you might notice 260 the problems in the first corner or ten miles ahead, depending mostly on your 261 choice of static vs dynamic runtime and third party libraries. Anyone using 262 software built in such way will at some point regret having done so. 263 264 When someone uses MSVC 6 without PSDK he is using a compiler back from 1998. 265 266 If the compiler has been updated with the installation of a service pack as 267 those mentioned in http://support.microsoft.com/kb/194022 the compiler can be 268 safely used to read source code, translate and make it object code. 269 270 But, even with the service packs mentioned above installed, the resulting 271 software generated in such an environment will be using outdated system 272 header files and libraries with bugs and security issues which have already 273 been addressed and fixed long time ago. 274 275 In order to make use of the updated system headers and fixed libraries 276 for MSVC 6, it is required that 'Platform SDK', PSDK from now onwards, 277 is installed. The specific PSDK that must be installed for MSVC 6 is the 278 February 2003 edition, which is the latest one supporting the MSVC 6 compiler, 279 this PSDK is also known as 'Windows Server 2003 PSDK' and can be downloaded 280 from http://www.microsoft.com/msdownload/platformsdk/sdkupdate/psdk-full.htm 281 282 So, building curl and libcurl with MSVC 6 without PSDK is absolutely 283 discouraged for the benefit of anyone using software built in such 284 environment. And it will not be supported in any way, as we could just 285 be hunting bugs which have already been fixed way back in 2003. 286 287 When building with MSVC 6 we attempt to detect if PSDK is not being used, 288 and if this is the case the build process will fail hard with an error 289 message stating that the February 2003 PSDK is required. This is done to 290 protect the unsuspecting and avoid PEBKAC issues. 291 292 Additionally it might happen that a die hard MSVC hacker still wants to 293 build curl and libcurl with MSVC 6 without PSDK installed, even knowing 294 that this is a highly discouraged and unsupported build environment. In 295 this case the brave of heart will be able to build in such an environment 296 with the requisite of defining preprocessor symbol ALLOW_MSVC6_WITHOUT_PSDK 297 in lib/config-win32.h and knowing that LDAP and IPv6 support will be missing. 298 299 MSVC from command line 300 ---------------------- 301 302 Run the 'vcvars32.bat' file to get a proper environment. The 303 vcvars32.bat file is part of the Microsoft development environment and 304 you may find it in 'C:\Program Files\Microsoft Visual Studio\vc98\bin' 305 provided that you installed Visual C/C++ 6 in the default directory. 306 307 Then run 'nmake vc' in curl's root directory. 308 309 If you want to compile with zlib support, you will need to build 310 zlib (http://www.gzip.org/zlib/) as well. Please read the zlib 311 documentation on how to compile zlib. Define the ZLIB_PATH environment 312 variable to the location of zlib.h and zlib.lib, for example: 313 314 set ZLIB_PATH=c:\zlib-1.2.8 315 316 Then run 'nmake vc-zlib' in curl's root directory. 317 318 If you want to compile with SSL support you need the OpenSSL package. 319 Please read the OpenSSL documentation on how to compile and install 320 the OpenSSL libraries. The build process of OpenSSL generates the 321 libeay32.dll and ssleay32.dll files in the out32dll subdirectory in 322 the OpenSSL home directory. OpenSSL static libraries (libeay32.lib, 323 ssleay32.lib, RSAglue.lib) are created in the out32 subdirectory. 324 325 Before running nmake define the OPENSSL_PATH environment variable with 326 the root/base directory of OpenSSL, for example: 327 328 set OPENSSL_PATH=c:\openssl-0.9.8y 329 330 Then run 'nmake vc-ssl' or 'nmake vc-ssl-dll' in curl's root 331 directory. 'nmake vc-ssl' will create a libcurl static and dynamic 332 libraries in the lib subdirectory, as well as a statically linked 333 version of curl.exe in the src subdirectory. This statically linked 334 version is a standalone executable not requiring any DLL at 335 runtime. This make method requires that you have the static OpenSSL 336 libraries available in OpenSSL's out32 subdirectory. 337 'nmake vc-ssl-dll' creates the libcurl dynamic library and 338 links curl.exe against libcurl and OpenSSL dynamically. 339 This executable requires libcurl.dll and the OpenSSL DLLs 340 at runtime. 341 Run 'nmake vc-ssl-zlib' to build with both ssl and zlib support. 342 343 MSVC 6 IDE 344 ---------- 345 346 A minimal VC++ 6.0 reference workspace (vc6curl.dsw) is available with the 347 source distribution archive to allow proper building of the two included 348 projects, the libcurl library and the curl tool. 349 350 1) Open the vs/vc6/vc6curl.dsw workspace with MSVC6's IDE. 351 2) Select 'Build' from top menu. 352 3) Select 'Batch Build' from dropdown menu. 353 4) Make sure that the eight project configurations are 'checked'. 354 5) Click on the 'Build' button. 355 6) Once the eight project configurations are built you are done. 356 357 Dynamic and static libcurl libraries are built in debug and release flavours, 358 and can be located each one in its own subdirectory, dll-debug, dll-release, 359 lib-debug and lib-release, all of them below the 'vs/vc6/lib' subdirectory. 360 361 In the same way four curl executables are created, each using its respective 362 library. The resulting curl executables are located in its own subdirectory, 363 dll-debug, dll-release, lib-debug and lib-release, below 'vs/vc6/src' subdir. 364 365 These reference VC++ 6.0 configurations are generated using the dynamic CRT. 366 367 Intentionally, these reference VC++ 6.0 projects and configurations don't use 368 third party libraries, such as OpenSSL or Zlib, to allow proper compilation 369 and configuration for all new users without further requirements. 370 371 If you need something more 'involved' you might adjust them for your own use, 372 or explore the world of makefiles described above 'MSVC from command line'. 373 374 Borland C++ compiler 375 --------------------- 376 377 Ensure that your build environment is properly set up to use the compiler 378 and associated tools. PATH environment variable must include the path to 379 bin subdirectory of your compiler installation, eg: c:\Borland\BCC55\bin 380 381 It is advisable to set environment variable BCCDIR to the base path of 382 the compiler installation. 383 384 set BCCDIR=c:\Borland\BCC55 385 386 In order to build a plain vanilla version of curl and libcurl run the 387 following command from curl's root directory: 388 389 make borland 390 391 To build curl and libcurl with zlib and OpenSSL support set environment 392 variables ZLIB_PATH and OPENSSL_PATH to the base subdirectories of the 393 already built zlib and OpenSSL libraries and from curl's root directory 394 run command: 395 396 make borland-ssl-zlib 397 398 libcurl library will be built in 'lib' subdirectory while curl tool 399 is built in 'src' subdirectory. In order to use libcurl library it is 400 advisable to modify compiler's configuration file bcc32.cfg located 401 in c:\Borland\BCC55\bin to reflect the location of libraries include 402 paths for example the '-I' line could result in something like: 403 404 -I"c:\Borland\BCC55\include;c:\curl\include;c:\openssl\inc32" 405 406 bcc3.cfg '-L' line could also be modified to reflect the location of 407 of libcurl library resulting for example: 408 409 -L"c:\Borland\BCC55\lib;c:\curl\lib;c:\openssl\out32" 410 411 In order to build sample program 'simple.c' from the docs\examples 412 subdirectory run following command from mentioned subdirectory: 413 414 bcc32 simple.c libcurl.lib cw32mt.lib 415 416 In order to build sample program simplessl.c an SSL enabled libcurl 417 is required, as well as the OpenSSL libeay32.lib and ssleay32.lib 418 libraries. 419 420 421 OTHER MSVC IDEs 422 --------------- 423 424 If you use VC++, Borland or similar compilers. Include all lib source 425 files in a static lib "project" (all .c and .h files that is). 426 (you should name it libcurl or similar) 427 428 Make the sources in the src/ drawer be a "win32 console application" 429 project. Name it curl. 430 431 432 Disabling Specific Protocols in Win32 builds 433 -------------------------------------------- 434 435 The configure utility, unfortunately, is not available for the Windows 436 environment, therefore, you cannot use the various disable-protocol 437 options of the configure utility on this platform. 438 439 However, you can use the following defines to disable specific 440 protocols: 441 442 HTTP_ONLY disables all protocols except HTTP 443 CURL_DISABLE_FTP disables FTP 444 CURL_DISABLE_LDAP disables LDAP 445 CURL_DISABLE_TELNET disables TELNET 446 CURL_DISABLE_DICT disables DICT 447 CURL_DISABLE_FILE disables FILE 448 CURL_DISABLE_TFTP disables TFTP 449 CURL_DISABLE_HTTP disables HTTP 450 451 If you want to set any of these defines you have the following 452 possibilities: 453 454 - Modify lib/config-win32.h 455 - Modify lib/curl_setup.h 456 - Modify lib/Makefile.vc6 457 - Add defines to Project/Settings/C/C++/General/Preprocessor Definitions 458 in the vc6libcurl.dsw/vc6libcurl.dsp Visual C++ 6 IDE project. 459 460 461 Using BSD-style lwIP instead of Winsock TCP/IP stack in Win32 builds 462 -------------------------------------------------------------------- 463 464 In order to compile libcurl and curl using BSD-style lwIP TCP/IP stack 465 it is necessary to make definition of preprocessor symbol USE_LWIPSOCK 466 visible to libcurl and curl compilation processes. To set this definition 467 you have the following alternatives: 468 469 - Modify lib/config-win32.h and src/config-win32.h 470 - Modify lib/Makefile.vc6 471 - Add definition to Project/Settings/C/C++/General/Preprocessor Definitions 472 in the vc6libcurl.dsw/vc6libcurl.dsp Visual C++ 6 IDE project. 473 474 Once that libcurl has been built with BSD-style lwIP TCP/IP stack support, 475 in order to use it with your program it is mandatory that your program 476 includes lwIP header file <lwip/opt.h> (or another lwIP header that includes 477 this) before including any libcurl header. Your program does not need the 478 USE_LWIPSOCK preprocessor definition which is for libcurl internals only. 479 480 Compilation has been verified with lwIP 1.4.0 and contrib-1.4.0 from: 481 482 http://download.savannah.gnu.org/releases/lwip/lwip-1.4.0.zip 483 http://download.savannah.gnu.org/releases/lwip/contrib-1.4.0.zip 484 485 This BSD-style lwIP TCP/IP stack support must be considered experimental 486 given that it has been verified that lwIP 1.4.0 still needs some polish, 487 and libcurl might yet need some additional adjustment, caveat emptor. 488 489 Important static libcurl usage note 490 ----------------------------------- 491 492 When building an application that uses the static libcurl library, you must 493 add '-DCURL_STATICLIB' to your CFLAGS. Otherwise the linker will look for 494 dynamic import symbols. 495 496 497Apple iOS and Mac OS X 498====================== 499 On recent Apple operating systems, curl can be built to use Apple's 500 SSL/TLS implementation, Secure Transport, instead of OpenSSL. To build with 501 Secure Transport for SSL/TLS, use the configure option --with-darwinssl. (It 502 is not necessary to use the option --without-ssl.) This feature requires iOS 503 5.0 or later, or OS X 10.5 ("Leopard") or later. 504 505 When Secure Transport is in use, the curl options --cacert and --capath and 506 their libcurl equivalents, will be ignored, because Secure Transport uses 507 the certificates stored in the Keychain to evaluate whether or not to trust 508 the server. This, of course, includes the root certificates that ship with 509 the OS. The --cert and --engine options, and their libcurl equivalents, are 510 currently unimplemented in curl with Secure Transport. 511 512 For OS X users: In OS X 10.8 ("Mountain Lion"), Apple made a major 513 overhaul to the Secure Transport API that, among other things, added 514 support for the newer TLS 1.1 and 1.2 protocols. To get curl to support 515 TLS 1.1 and 1.2, you must build curl on Mountain Lion or later, or by 516 using the equivalent SDK. If you set the MACOSX_DEPLOYMENT_TARGET 517 environmental variable to an earlier version of OS X prior to building curl, 518 then curl will use the new Secure Transport API on Mountain Lion and later, 519 and fall back on the older API when the same curl binary is executed on 520 older cats. For example, running these commands in curl's directory in the 521 shell will build the code such that it will run on cats as old as OS X 10.6 522 ("Snow Leopard") (using bash): 523 524 export MACOSX_DEPLOYMENT_TARGET="10.6" 525 ./configure --with-darwinssl 526 make 527 528 529IBM OS/2 530======== 531 Building under OS/2 is not much different from building under unix. 532 You need: 533 534 - emx 0.9d 535 - GNU make 536 - GNU patch 537 - ksh 538 - GNU bison 539 - GNU file utilities 540 - GNU sed 541 - autoconf 2.13 542 543 If you want to build with OpenSSL or OpenLDAP support, you'll need to 544 download those libraries, too. Dirk Ohme has done some work to port SSL 545 libraries under OS/2, but it looks like he doesn't care about emx. You'll 546 find his patches on: http://come.to/Dirk_Ohme 547 548 If during the linking you get an error about _errno being an undefined 549 symbol referenced from the text segment, you need to add -D__ST_MT_ERRNO__ 550 in your definitions. 551 552 If everything seems to work fine but there's no curl.exe, you need to add 553 -Zexe to your linker flags. 554 555 If you're getting huge binaries, probably your makefiles have the -g in 556 CFLAGS. 557 558 559VMS 560=== 561 (The VMS section is in whole contributed by the friendly Nico Baggus) 562 563 Curl seems to work with FTP & HTTP other protocols are not tested. (the 564 perl http/ftp testing server supplied as testing too cannot work on VMS 565 because vms has no concept of fork(). [ I tried to give it a whack, but 566 that's of no use. 567 568 SSL stuff has not been ported. 569 570 Telnet has about the same issues as for Win32. When the changes for Win32 571 are clear maybe they'll work for VMS too. The basic problem is that select 572 ONLY works for sockets. 573 574 Marked instances of fopen/[f]stat that might become a problem, especially 575 for non stream files. In this regard, the files opened for writing will be 576 created stream/lf and will thus be safe. Just keep in mind that non-binary 577 read/wring from/to files will have a records size limit of 32767 bytes 578 imposed. 579 580 Stat to get the size of the files is again only safe for stream files & 581 fixed record files without implied CC. 582 583 -- My guess is that only allowing access to stream files is the quickest 584 way to get around the most issues. Therefore all files need to to be 585 checked to be sure they will be stream/lf before processing them. This is 586 the easiest way out, I know. The reason for this is that code that needs to 587 report the filesize will become a pain in the ass otherwise. 588 589 Exit status.... Well we needed something done here, 590 591 VMS has a structured exist status: 592 | 3 | 2 | 1 | 0| 593 |1098|765432109876|5432109876543|210| 594 +----+------------+-------------+---+ 595 |Ctrl| Facility | Error code |sev| 596 +----+------------+-------------+---+ 597 598 With the Ctrl-bits an application can tell if part or the whole message has 599 already been printed from the program, DCL doesn't need to print it again. 600 601 Facility - basically the program ID. A code assigned to the program 602 the name can be fetched from external or internal message libraries 603 Error code - the err codes assigned by the application 604 Sev. - severity: Even = error, off = non error 605 0 = Warning 606 1 = Success 607 2 = Error 608 3 = Information 609 4 = Fatal 610 <5-7> reserved. 611 612 This all presents itself with: 613 %<FACILITY>-<Sev>-<Errorname>, <Error message> 614 615 See also the src/curlmsg.msg file, it has the source for the messages In 616 src/main.c a section is devoted to message status values, the globalvalues 617 create symbols with certain values, referenced from a compiled message 618 file. Have all exit function use a exit status derived from a translation 619 table with the compiled message codes. 620 621 This was all compiled with: 622 623 Compaq C V6.2-003 on OpenVMS Alpha V7.1-1H2 624 625 So far for porting notes as of: 626 13-jul-2001 627 N. Baggus 628 629 630QNX 631=== 632 (This section was graciously brought to us by David Bentham) 633 634 As QNX is targeted for resource constrained environments, the QNX headers 635 set conservative limits. This includes the FD_SETSIZE macro, set by default 636 to 32. Socket descriptors returned within the CURL library may exceed this, 637 resulting in memory faults/SIGSEGV crashes when passed into select(..) 638 calls using fd_set macros. 639 640 A good all-round solution to this is to override the default when building 641 libcurl, by overriding CFLAGS during configure, example 642 # configure CFLAGS='-DFD_SETSIZE=64 -g -O2' 643 644 645RISC OS 646======= 647 The library can be cross-compiled using gccsdk as follows: 648 649 CC=riscos-gcc AR=riscos-ar RANLIB='riscos-ar -s' ./configure \ 650 --host=arm-riscos-aof --without-random --disable-shared 651 make 652 653 where riscos-gcc and riscos-ar are links to the gccsdk tools. 654 You can then link your program with curl/lib/.libs/libcurl.a 655 656 657AmigaOS 658======= 659 (This section was graciously brought to us by Diego Casorran) 660 661 To build cURL/libcurl on AmigaOS just type 'make amiga' ... 662 663 What you need is: (not tested with others versions) 664 665 GeekGadgets / gcc 2.95.3 (http://www.geekgadgets.org/) 666 667 AmiTCP SDK v4.3 (http://www.aminet.net/comm/tcp/AmiTCP-SDK-4.3.lha) 668 669 Native Developer Kit (http://www.amiga.com/3.9/download/NDK3.9.lha) 670 671 As no ixemul.library is required you will be able to build it for 672 WarpOS/PowerPC (not tested by me), as well a MorphOS version should be 673 possible with no problems. 674 675 To enable SSL support, you need a OpenSSL native version (without ixemul), 676 you can find a precompiled package at http://amiga.sourceforge.net/OpenSSL/ 677 678 679NetWare 680======= 681 To compile curl.nlm / libcurl.nlm you need: 682 - either any gcc / nlmconv, or CodeWarrior 7 PDK 4 or later. 683 - gnu make and awk running on the platform you compile on; 684 native Win32 versions can be downloaded from: 685 http://www.gknw.net/development/prgtools/ 686 - recent Novell LibC SDK available from: 687 http://developer.novell.com/ndk/libc.htm 688 - or recent Novell CLib SDK available from: 689 http://developer.novell.com/ndk/clib.htm 690 - optional recent Novell CLDAP SDK available from: 691 http://developer.novell.com/ndk/cldap.htm 692 - optional zlib sources (static or dynamic linking with zlib.imp); 693 sources with NetWare Makefile can be obtained from: 694 http://www.gknw.net/mirror/zlib/ 695 - optional OpenSSL sources (version 0.9.8 or later build with BSD sockets); 696 you can find precompiled packages at: 697 http://www.gknw.net/development/ossl/netware/ 698 for CLIB-based builds OpenSSL 0.9.8h or later is required - earlier versions 699 don't support building with CLIB BSD sockets. 700 - optional SSH2 sources (version 0.17 or later); 701 702 Set a search path to your compiler, linker and tools; on Linux make 703 sure that the var OSTYPE contains the string 'linux'; set the var 704 NDKBASE to point to the base of your Novell NDK; and then type 705 'make netware' from the top source directory; other targets available 706 are 'netware-ssl', 'netware-ssl-zlib', 'netware-zlib' and 'netware-ares'; 707 if you need other combinations you can control the build with the 708 environment variables WITH_SSL, WITH_ZLIB, WITH_ARES, WITH_SSH2, and 709 ENABLE_IPV6; you can set LINK_STATIC=1 to link curl.nlm statically. 710 By default LDAP support is enabled, however currently you will need a patch 711 in order to use the CLDAP NDK with BSD sockets (Novell Bug 300237): 712 http://www.gknw.net/test/curl/cldap_ndk/ldap_ndk.diff 713 I found on some Linux systems (RH9) that OS detection didn't work although 714 a 'set | grep OSTYPE' shows the var present and set; I simply overwrote it 715 with 'OSTYPE=linux-rh9-gnu' and the detection in the Makefile worked... 716 Any help in testing appreciated! 717 Builds automatically created 8 times a day from current git are here: 718 http://www.gknw.net/mirror/curl/autobuilds/ 719 the status of these builds can be viewed at the autobuild table: 720 http://curl.haxx.se/dev/builds.html 721 722 723eCos 724==== 725 curl does not use the eCos build system, so you must first build eCos 726 separately, then link curl to the resulting eCos library. Here's a sample 727 configure line to do so on an x86 Linux box targeting x86: 728 729 GCCLIB=`gcc -print-libgcc-file-name` && \ 730 CFLAGS="-D__ECOS=1 -nostdinc -I$ECOS_INSTALL/include \ 731 -I`dirname $GCCLIB`/include" \ 732 LDFLAGS="-nostdlib -Wl,--gc-sections -Wl,-static \ 733 -L$ECOS_INSTALL/lib -Ttarget.ld -ltarget" \ 734 ./configure --host=i386 --disable-shared \ 735 --without-ssl --without-zlib --disable-manual --disable-ldap 736 737 In most cases, eCos users will be using libcurl from within a custom 738 embedded application. Using the standard 'curl' executable from 739 within eCos means facing the limitation of the standard eCos C 740 startup code which does not allow passing arguments in main(). To 741 run 'curl' from eCos and have it do something useful, you will need 742 to either modify the eCos startup code to pass in some arguments, or 743 modify the curl application itself to retrieve its arguments from 744 some location set by the bootloader or hard-code them. 745 746 Something like the following patch could be used to hard-code some 747 arguments. The MTAB_ENTRY line mounts a RAM disk as the root filesystem 748 (without mounting some kind of filesystem, eCos errors out all file 749 operations which curl does not take to well). The next section synthesizes 750 some command-line arguments for curl to use, in this case to direct curl 751 to read further arguments from a file. It then creates that file on the 752 RAM disk and places within it a URL to download: a file: URL that 753 just happens to point to the configuration file itself. The results 754 of running curl in this way is the contents of the configuration file 755 printed to the console. 756 757--- src/main.c 19 Jul 2006 19:09:56 -0000 1.363 758+++ src/main.c 24 Jul 2006 21:37:23 -0000 759@@ -4286,11 +4286,31 @@ 760 } 761 762 763+#ifdef __ECOS 764+#include <cyg/fileio/fileio.h> 765+MTAB_ENTRY( testfs_mte1, 766+ "/", 767+ "ramfs", 768+ "", 769+ 0); 770+#endif 771 772 int main(int argc, char *argv[]) 773 { 774 int res; 775 struct Configurable config; 776+#ifdef __ECOS 777+ char *args[] = {"ecos-curl", "-K", "curlconf.txt"}; 778+ FILE *f; 779+ argc = sizeof(args)/sizeof(args[0]); 780+ argv = args; 781+ 782+ f = fopen("curlconf.txt", "w"); 783+ if (f) { 784+ fprintf(f, "--url file:curlconf.txt"); 785+ fclose(f); 786+ } 787+#endif 788 memset(&config, 0, sizeof(struct Configurable)); 789 790 config.errors = stderr; /* default errors to stderr */ 791 792 793Minix 794===== 795 curl can be compiled on Minix 3 using gcc or ACK (starting with 796 ver. 3.1.3). Ensure that GNU gawk and bash are both installed and 797 available in the PATH. 798 799 ACK 800 --- 801 Increase the heap sizes of the compiler with the command: 802 803 binsizes xxl 804 805 then configure and compile curl with: 806 807 ./configure CC=cc LD=cc AR=/usr/bin/aal GREP=grep \ 808 CPPFLAGS='-D_POSIX_SOURCE=1 -I/usr/local/include' 809 make 810 chmem =256000 src/curl 811 812 GCC 813 --- 814 Make sure gcc is in your PATH with the command: 815 816 export PATH=/usr/gnu/bin:$PATH 817 818 then configure and compile curl with: 819 820 ./configure CC=gcc AR=/usr/gnu/bin/gar GREP=grep 821 make 822 chmem =256000 src/curl 823 824 825Symbian OS 826========== 827 The Symbian OS port uses the Symbian build system to compile. From the 828 packages/Symbian/group/ directory, run: 829 830 bldmake bldfiles 831 abld build 832 833 to compile and install curl and libcurl using SBSv1. If your Symbian 834 SDK doesn't include support for P.I.P.S., you will need to contact 835 your SDK vendor to obtain that first. 836 837 838VxWorks 839======== 840 Build for VxWorks is performed using cross compilation. 841 That means you build on Windows machine using VxWorks tools and 842 run the built image on the VxWorks device. 843 844 To build libcurl for VxWorks you need: 845 846 - CYGWIN (free, http://cygwin.com/) 847 - Wind River Workbench (commercial) 848 849 If you have CYGWIN and Workbench installed on you machine 850 follow after next steps: 851 852 1. Open the Command Prompt window and change directory ('cd') 853 to the libcurl 'lib' folder. 854 2. Add CYGWIN 'bin' folder to the PATH environment variable. 855 For example, type 'set PATH=C:/embedded/cygwin/bin;%PATH%'. 856 3. Adjust environment variables defined in 'Environment' section 857 of the Makefile.vxworks file to point to your software folders. 858 4. Build the libcurl by typing 'make -f ./Makefile.vxworks' 859 860 As a result the libcurl.a library should be created in the 'lib' folder. 861 To clean the build results type 'make -f ./Makefile.vxworks clean'. 862 863 864Android 865======= 866 Method using the static makefile: 867 - see the build notes in the packages/Android/Android.mk file. 868 869 Method using a configure cross-compile (tested with Android NDK r7c, r8): 870 - prepare the toolchain of the Android NDK for standalone use; this can 871 be done by invoking the script: 872 ./build/tools/make-standalone-toolchain.sh 873 which creates a usual cross-compile toolchain. Lets assume that you put 874 this toolchain below /opt then invoke configure with something like: 875 export PATH=/opt/arm-linux-androideabi-4.4.3/bin:$PATH 876 ./configure --host=arm-linux-androideabi [more configure options] 877 make 878 - if you want to compile directly from our GIT repo you might run into 879 this issue with older automake stuff: 880 checking host system type... 881 Invalid configuration `arm-linux-androideabi': 882 system `androideabi' not recognized 883 configure: error: /bin/sh ./config.sub arm-linux-androideabi failed 884 this issue can be fixed with using more recent versions of config.sub 885 and config.guess which can be obtained here: 886 http://git.savannah.gnu.org/gitweb/?p=config.git;a=tree 887 you need to replace your system-own versions which usually can be 888 found in your automake folder: 889 find /usr -name config.sub 890 891 Wrapper for pkg-config 892 - In order to make proper use of pkg-config so that configure is able to 893 find all dependencies you should create a wrapper script for pkg-config; 894 file /opt/arm-linux-androideabi-4.4.3/bin/arm-linux-androideabi-pkg-config: 895 896 #!/bin/sh 897 SYSROOT=$(dirname ${0%/*})/sysroot 898 export PKG_CONFIG_DIR= 899 export PKG_CONFIG_LIBDIR=${SYSROOT}/usr/local/lib/pkgconfig:${SYSROOT}/usr/share/pkgconfig 900 export PKG_CONFIG_SYSROOT_DIR=${SYSROOT} 901 exec pkg-config "$@" 902 903 also create a copy or symlink with name arm-unknown-linux-androideabi-pkg-config. 904 905 906CROSS COMPILE 907============= 908 (This section was graciously brought to us by Jim Duey, with additions by 909 Dan Fandrich) 910 911 Download and unpack the cURL package. 912 913 'cd' to the new directory. (e.g. cd curl-7.12.3) 914 915 Set environment variables to point to the cross-compile toolchain and call 916 configure with any options you need. Be sure and specify the '--host' and 917 '--build' parameters at configuration time. The following script is an 918 example of cross-compiling for the IBM 405GP PowerPC processor using the 919 toolchain from MonteVista for Hardhat Linux. 920 921 (begin script) 922 923 #! /bin/sh 924 925 export PATH=$PATH:/opt/hardhat/devkit/ppc/405/bin 926 export CPPFLAGS="-I/opt/hardhat/devkit/ppc/405/target/usr/include" 927 export AR=ppc_405-ar 928 export AS=ppc_405-as 929 export LD=ppc_405-ld 930 export RANLIB=ppc_405-ranlib 931 export CC=ppc_405-gcc 932 export NM=ppc_405-nm 933 934 ./configure --target=powerpc-hardhat-linux \ 935 --host=powerpc-hardhat-linux \ 936 --build=i586-pc-linux-gnu \ 937 --prefix=/opt/hardhat/devkit/ppc/405/target/usr/local \ 938 --exec-prefix=/usr/local 939 940 (end script) 941 942 You may also need to provide a parameter like '--with-random=/dev/urandom' 943 to configure as it cannot detect the presence of a random number 944 generating device for a target system. The '--prefix' parameter 945 specifies where cURL will be installed. If 'configure' completes 946 successfully, do 'make' and 'make install' as usual. 947 948 In some cases, you may be able to simplify the above commands to as 949 little as: 950 951 ./configure --host=ARCH-OS 952 953 954REDUCING SIZE 955============= 956 There are a number of configure options that can be used to reduce the 957 size of libcurl for embedded applications where binary size is an 958 important factor. First, be sure to set the CFLAGS variable when 959 configuring with any relevant compiler optimization flags to reduce the 960 size of the binary. For gcc, this would mean at minimum the -Os option, 961 and potentially the -march=X and -mdynamic-no-pic options as well, e.g. 962 963 ./configure CFLAGS='-Os' ... 964 965 Note that newer compilers often produce smaller code than older versions 966 due to improved optimization. 967 968 Be sure to specify as many --disable- and --without- flags on the configure 969 command-line as you can to disable all the libcurl features that you 970 know your application is not going to need. Besides specifying the 971 --disable-PROTOCOL flags for all the types of URLs your application 972 will not use, here are some other flags that can reduce the size of the 973 library: 974 975 --disable-ares (disables support for the C-ARES DNS library) 976 --disable-cookies (disables support for HTTP cookies) 977 --disable-crypto-auth (disables HTTP cryptographic authentication) 978 --disable-ipv6 (disables support for IPv6) 979 --disable-manual (disables support for the built-in documentation) 980 --disable-proxy (disables support for HTTP and SOCKS proxies) 981 --disable-verbose (eliminates debugging strings and error code strings) 982 --enable-hidden-symbols (eliminates unneeded symbols in the shared library) 983 --without-libidn (disables support for the libidn DNS library) 984 --without-librtmp (disables support for RTMP) 985 --without-ssl (disables support for SSL/TLS) 986 --without-zlib (disables support for on-the-fly decompression) 987 988 The GNU compiler and linker have a number of options that can reduce the 989 size of the libcurl dynamic libraries on some platforms even further. 990 Specify them by providing appropriate CFLAGS and LDFLAGS variables on the 991 configure command-line, e.g. 992 CFLAGS="-Os -ffunction-sections -fdata-sections \ 993 -fno-unwind-tables -fno-asynchronous-unwind-tables" \ 994 LDFLAGS="-Wl,-s -Wl,-Bsymbolic -Wl,--gc-sections" 995 996 Be sure also to strip debugging symbols from your binaries after 997 compiling using 'strip' (or the appropriate variant if cross-compiling). 998 If space is really tight, you may be able to remove some unneeded 999 sections of the shared library using the -R option to objcopy (e.g. the 1000 .comment section). 1001 1002 Using these techniques it is possible to create a basic HTTP-only shared 1003 libcurl library for i386 Linux platforms that is only 114 KiB in size, and 1004 an FTP-only library that is 115 KiB in size (as of libcurl version 7.35.0, 1005 using gcc 4.8.2). 1006 1007 You may find that statically linking libcurl to your application will 1008 result in a lower total size than dynamically linking. 1009 1010 Note that the curl test harness can detect the use of some, but not all, of 1011 the --disable statements suggested above. Use will cause tests relying on 1012 those features to fail. The test harness can be manually forced to skip 1013 the relevant tests by specifying certain key words on the runtests.pl 1014 command line. Following is a list of appropriate key words: 1015 1016 --disable-cookies !cookies 1017 --disable-manual !--manual 1018 --disable-proxy !HTTP\ proxy !proxytunnel !SOCKS4 !SOCKS5 1019 1020 1021PORTS 1022===== 1023 This is a probably incomplete list of known hardware and operating systems 1024 that curl has been compiled for. If you know a system curl compiles and 1025 runs on, that isn't listed, please let us know! 1026 1027 - Alpha DEC OSF 4 1028 - Alpha Digital UNIX v3.2 1029 - Alpha FreeBSD 4.1, 4.5 1030 - Alpha Linux 2.2, 2.4 1031 - Alpha NetBSD 1.5.2 1032 - Alpha OpenBSD 3.0 1033 - Alpha OpenVMS V7.1-1H2 1034 - Alpha Tru64 v5.0 5.1 1035 - AVR32 Linux 1036 - ARM Android 1.5, 2.1, 2.3, 3.2, 4.x 1037 - ARM INTEGRITY 1038 - ARM iOS 1039 - Cell Linux 1040 - Cell Cell OS 1041 - HP-PA HP-UX 9.X 10.X 11.X 1042 - HP-PA Linux 1043 - HP3000 MPE/iX 1044 - MicroBlaze uClinux 1045 - MIPS IRIX 6.2, 6.5 1046 - MIPS Linux 1047 - OS/400 1048 - Pocket PC/Win CE 3.0 1049 - Power AIX 3.2.5, 4.2, 4.3.1, 4.3.2, 5.1, 5.2 1050 - PowerPC Darwin 1.0 1051 - PowerPC INTEGRITY 1052 - PowerPC Linux 1053 - PowerPC Mac OS 9 1054 - PowerPC Mac OS X 1055 - SH4 Linux 2.6.X 1056 - SH4 OS21 1057 - SINIX-Z v5 1058 - Sparc Linux 1059 - Sparc Solaris 2.4, 2.5, 2.5.1, 2.6, 7, 8, 9, 10 1060 - Sparc SunOS 4.1.X 1061 - StrongARM (and other ARM) RISC OS 3.1, 4.02 1062 - StrongARM/ARM7/ARM9 Linux 2.4, 2.6 1063 - StrongARM NetBSD 1.4.1 1064 - Symbian OS (P.I.P.S.) 9.x 1065 - TPF 1066 - Ultrix 4.3a 1067 - UNICOS 9.0 1068 - i386 BeOS 1069 - i386 DOS 1070 - i386 eCos 1.3.1 1071 - i386 Esix 4.1 1072 - i386 FreeBSD 1073 - i386 HURD 1074 - i386 Haiku OS 1075 - i386 Linux 1.3, 2.0, 2.2, 2.3, 2.4, 2.6 1076 - i386 Mac OS X 1077 - i386 MINIX 3.1 1078 - i386 NetBSD 1079 - i386 Novell NetWare 1080 - i386 OS/2 1081 - i386 OpenBSD 1082 - i386 QNX 6 1083 - i386 SCO unix 1084 - i386 Solaris 2.7 1085 - i386 Windows 95, 98, ME, NT, 2000, XP, 2003 1086 - i486 ncr-sysv4.3.03 (NCR MP-RAS) 1087 - ia64 Linux 2.3.99 1088 - m68k AmigaOS 3 1089 - m68k Linux 1090 - m68k uClinux 1091 - m68k OpenBSD 1092 - m88k dg-dgux5.4R3.00 1093 - s390 Linux 1094 - x86_64 Linux 1095 - XScale/PXA250 Linux 2.4 1096 - Nios II uClinux 1097 1098Useful URLs 1099=========== 1100 1101axTLS http://axtls.sourceforge.net/ 1102c-ares http://c-ares.haxx.se/ 1103GNU GSS http://www.gnu.org/software/gss/ 1104GnuTLS http://www.gnu.org/software/gnutls/ 1105Heimdal http://www.pdc.kth.se/heimdal/ 1106libidn http://www.gnu.org/software/libidn/ 1107libmetalink https://launchpad.net/libmetalink/ 1108libssh2 http://www.libssh2.org/ 1109MIT Kerberos http://web.mit.edu/kerberos/www/dist/ 1110NSS http://www.mozilla.org/projects/security/pki/nss/ 1111OpenLDAP http://www.openldap.org/ 1112OpenSSL http://www.openssl.org/ 1113PolarSSL http://polarssl.org/ 1114yassl http://www.yassl.com/ 1115Zlib http://www.zlib.net/ 1116 1117MingW http://www.mingw.org/ 1118MinGW-w64 http://mingw-w64.sourceforge.net/ 1119OpenWatcom http://www.openwatcom.org/ 1120