From 5fa809e7273c535bc5781e48e4f02fe01e76e1ee Mon Sep 17 00:00:00 2001 From: ng0 Date: Mon, 27 May 2019 17:54:16 +0000 Subject: README --- README | 92 +++++++++++++++++++++++++++++++++++++----------------------------- 1 file changed, 52 insertions(+), 40 deletions(-) diff --git a/README b/README index d49b95abe..04779b7a2 100644 --- a/README +++ b/README @@ -1,40 +1,61 @@ -libgnurl is a fork of libcurl with the following major changes: +gnurl +===== + +gnurl / libgnurl is a fork of curl/libcurl with the following major changes: + +* Enforced compilation requirements: + * libgnurl must be compiled so that it supports only HTTP and HTTPS + (remove Gopher, SSH, IMAP, etc.) + * libgnurl must be compiled so that it supports only GnuTLS + (remove CaySSL, QsoSSL, GSKit, etc.) + * removed support for NTLM, GSSAPI, SPNEGO, LDAP, metalink, HTTP2 + * We recommend to build GnuTLS with DANE support, provided by 'unbound'. + This is optional. + +* Changes to the code: + * renamed the library binary from 'libcurl' to 'lignurl' + * renamed files to ensure a system-wide installation of + libgnurl does not result in namespace collisions with libcurl + * adjustments to the testsuite to address the gnurl specific build + * dropped auto-generation of ngroff man page in favor of mdoc page, + with the endgoal to drop the build-time dependency on groff and + to provide a more appropriate documentation for gnurl. + + +Usage notes +----------- +* exported symbols were NOT renamed, so they all still have the + curl prefix; you should be able to start using libgnurl simply + by changing -lcurl to -lgnurl (and adjusting the header location). -Compilation requirements: -* libgnurl must be compiled so that it supports only HTTP and HTTPS - (remove Gopher, SSH, IMAP, etc.) -* libgnurl must be compiled so that it supports only GnuTLS - (remove CaySSL, QsoSSL, GSKit, etc.) -* removed support for NTLM, GSSAPI, SPNEGO, LDAP, metalink, HTTP2 -* We recommend to build GnuTLS with DANE support, provided by 'unbound'. - This is optional. +Using libgnurl: -If you are a package maintainer: Do not enable the latest features -curl likes to add, do not add libnghttp2 or libpsl support. +Projects that use cURL only for HTTP/HTTPS and that would work with +GnuTLS should be able to switch to libgnurl by changing "-lcurl" to +"-lgnurl". That's it. No changes to the source code should be +required. Continue to read the cURL documentation --- as libgnurl +strives for bug-for-bug compatibility with the HTTP/HTTPS/GnuTLS +subset of cURL. However, we're happy to add new features relating to +this core subset. -Changes to the code: -* renamed the library binary from 'libcurl' to 'lignurl' -* renamed files to ensure a system-wide installation of - libgnurl does not result in namespace collisions with libcurl -* adjustments to the testsuite to address the gnurl specific build -* Changes to be written: - * Replace the release process with more automatization -Usage notes: -* exported symbols were NOT renamed, so they still all have the - curl prefix; you should be able to start using libgnurl simply - by changing -lcurl to -lgnurl. +Installation, Building +---------------------- Note that the compilation requirements are still not fully -hardcoded, but work on this is in progress since gnURL 7.56.1-2. -If you compile libgnurl, please pass '--disable-ntlm-wb' to the -configure script. So instead of just running +hardcoded, but work on this is in progress. +The method which is applied at the moment after iterating through +a couple of other methods, is to hard fail when unsupported switches +are encountered. If you wan a shortcut, read (or install!) +net/gnurl from pkgsrc (http://pkgsrc.org). The configure-gnurl file +I included here which usually is up to date might serve as reference +too. - ./configure - -you will run +If you compile libgnurl, please pass '--disable-ntlm-wb' to the +configure script. - ./configure --disable-ntlm-wb +If you are a package maintainer: Do not enable the latest features +curl likes to add, do not add libnghttp2 or libpsl support. Naturally, you're free to specify additional options, such as "--prefix". Please keep in mind that you might have to pass @@ -64,7 +85,8 @@ system distribution side: --disable-file --disable-ftp --disable-smb --disable-ares -Motivation: +Initial motivation +------------------ cURL supports a bunch of crypto backends. GNUnet requires the use of GnuTLS, but other variants are used by some distributions. Supporting @@ -145,16 +167,6 @@ small footprint and uniform experience for developers regardless of how libcurl was compiled. -Using libgnurl: - -Projects that use cURL only for HTTP/HTTPS and that would work with -GnuTLS should be able to switch to libgnurl by changing "-lcurl" to -"-lgnurl". That's it. No changes to the source code should be -required. Continue to read the cURL documentation --- as libgnurl -strives for bug-for-bug compatibility with the HTTP/HTTPS/GnuTLS -subset of cURL. However, we're happy to add new features relating to -this core subset and might be easier to convince than the cURL -developers. THANKS: -- cgit v1.2.3