README

   1 libgpg-error
   2 ============
   3
   4 This is a library that defines common error values for all GnuPG
   5 components.  Among these are GPG, GPGSM, GPGME, GPG-Agent, libgcrypt,
   6 Libksba, DirMngr, Pinentry, SmartCard Daemon and more.
   7
   8 libgpg-error is free software; you can redistribute it and/or modify
   9 it under the terms of the GNU Lesser General Public License as
  10 published by the Free Software Foundation; either version 2.1 of the
  11 License, or (at your option) any later version.  See the file
  12 COPYING.LIB for copyright and warranty information.  See the file
  13 AUTHORS for a list of authors and important mail addresses.
  14
  15 However, some files (for example src/mkerrnos.awk) used in the build
  16 process of the library are covered by a different license.  Please see
  17 the header of these files and the file COPYING for copyright and
  18 warranty information on these files.  A special exception in the
  19 copyright license of these files makes sure that the output in the
  20 build process, which is used in libgpg-error, is not affected by the
  21 GPL.
  22
  23
  24 Installation
  25 ------------
  26
  27 Please read the file INSTALL!
  28
  29 Here is a quick summary:
  30
  31 1) Check that you have unmodified sources.  You can find instructions
  32    how to verify the sources below.  Don't skip this - it is an
  33    important step!
  34
  35 2) Unpack the archive.  With GNU tar you can do it this way:
  36    "tar xjvf libgpg-error-x.y.tar.bz2"
  37
  38 3) "cd libgpg-error-x.y"
  39
  40 4) "./configure"
  41
  42 5) "make"
  43
  44 6) "make install"
  45
  46
  47 How to Verify the Source
  48 ------------------------
  49
  50 In order to check that the version of libgpg-error which you are going
  51 to install is an original and unmodified copy of the original, you can
  52 do it in one of the following ways:
  53
  54 a) If you already have a trusted version of GnuPG installed, you can
  55    simply check the supplied signature:
  56
  57    $ gpg --verify libgpg-error-x.y.tar.bz2.sig
  58
  59    This checks that the detached signature libgpg-error-x.y.tar.bz2.sig
  60    is indeed a a signature of libgpg-error-x.y.tar.bz2.
  61
  62    Please note that you have to use an old version of GnuPG to do all
  63    this stuff.  *Never* use the version which was built using the
  64    library you are trying to verify!
  65
  66 b) If you don't have any a trusted version of GnuPG, you can attempt
  67    to verify the SHA1 checksum, using a trusted version of the sha1sum
  68    program:
  69
  70    $ sha1sum libgpg-error-x.y.tar.bz2
  71
  72    This should yield an output _similar_ to this:
  73
  74    610064e5b77700f5771c8fde2691c4365e1ca100  libgpg-error-x.y.tar.bz2
  75
  76    Now check that this checksum is _exactly_ the same as the one
  77    published via the announcement list and probably via Usenet.
  78
  79
  80 Hints
  81 -----
  82
  83 To build for Windows you you may use the convenience command:
  84
  85    ./autogen.sh --build-w32
  86
  87 which runs configure with suitable options.  For WindowsCE the command
  88 is:
  89
  90    ./autogen.sh --build-w32ce
  91
  92 There is also _experimental_ support for building a 64 bit Windows
  93 version:
  94
  95    ./autogen.sh --build-w64
  96
  97
  98 Cross-Compiling
  99 ---------------
 100
 101 Libgpg-error needs to figure out some platform specific properties.
 102 These are used to build the platform specific gpg-error.h file.  The
 103 detection is done during build time but can't be done when
 104 cross-compiling.  Thus if you run into an error during building you
 105 need to figure out these values.  You may use these commands:
 106
 107   build="$(build-aux/config.guess)"
 108   ./configure --prefix=TARGETDIR --host=TARGET --build=$build
 109   cd src
 110   make gen-posix-lock-obj
 111   scp gen-posix-lock-obj TARGET:
 112   ssh TARGET ./gen-posix-lock-obj >tmp.h
 113   mv tmp.h "syscfg/$(awk 'NR==1 {print $2}' tmp.h)"
 114
 115 If you are using a VPATH build adjust accordingly.  If this all works
 116 for you (make sure to run the test programs on the target platform),
 117 please send the generated file to the gnupg-devel mailing list so that
 118 we can include it in the next release.
 119
 120
 121
 122 Known Problems
 123 --------------
 124
 125 On Windows, WSA Error Codes can be provided as system error codes and
 126 will be transparently converted to the corresponding gpg error codes.
 127 There are two problems with this support:
 128
 129 * Not all error codes corresponding to WSA Error codes have a detailed
 130   description when printed with gpg_strerror.  Some will default to
 131   "Unknown error" for pretty printing.  For example, WSAEHOSTDOWN will
 132   be translated to GPG_ERR_EHOSTDOWN, but there is no corresponding
 133   EHOSTDOWN in Windows and thus gpg_strerror will default to "Unknown
 134   error" as printed by the system's strerror function for the argument
 135   WSAEHOSTDOWN.  (This could be fixed by adding our own error strings
 136   replacing or extending the system error strings, including their
 137   translations).
 138
 139 * The translation to a gpg error code and back to a system error code
 140   in some cases does not preserve information.  For example, the error code
 141   WSAEACCES translates to GPG_ERR_EACCES, which translates back to
 142   EACCES.
 143
 144 Any WSA Error code has either the first problem or the second (but not
 145 both), depending on if there is a corresponding Windows error code.