diff --git a/INSTALL b/INSTALL index 5458714e1..9e9642898 100644 --- a/INSTALL +++ b/INSTALL @@ -1,234 +1,238 @@ Installation Instructions ************************* Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004, 2005, 2006 Free Software Foundation, Inc. This file is free documentation; the Free Software Foundation gives unlimited permission to copy, distribute and modify it. Basic Installation ================== Briefly, the shell commands `./configure; make; make install' should configure, build, and install this package. The following more-detailed instructions are generic; see the `README' file for instructions specific to this package. The `configure' shell script attempts to guess correct values for various system-dependent variables used during compilation. It uses those values to create a `Makefile' in each directory of the package. It may also create one or more `.h' files containing system-dependent definitions. Finally, it creates a shell script `config.status' that you can run in the future to recreate the current configuration, and a file `config.log' containing compiler output (useful mainly for debugging `configure'). It can also use an optional file (typically called `config.cache' and enabled with `--cache-file=config.cache' or simply `-C') that saves the results of its tests to speed up reconfiguring. Caching is disabled by default to prevent problems with accidental use of stale cache files. If you need to do unusual things to compile the package, please try to figure out how `configure' could check whether to do them, and mail diffs or instructions to the address given in the `README' so they can be considered for the next release. If you are using the cache, and at some point `config.cache' contains results you don't want to keep, you may remove or edit it. The file `configure.ac' (or `configure.in') is used to create `configure' by a program called `autoconf'. You need `configure.ac' if you want to change it or regenerate `configure' using a newer version of `autoconf'. -The simplest way to compile this package is: +The suggested way to compile this package is: - 1. `cd' to the directory containing the package's source code and type - `./configure' to configure the package for your system. + 1. `cd' to the directory containing the package's source code and + create a new directory named `build'. Then `cd' to that + directory and type `../configure' to configure the package for + your system. Running `configure' might take a while. While running, it prints some messages telling which features it is checking for. 2. Type `make' to compile the package. 3. Optionally, type `make check' to run any self-tests that come with the package. 4. Type `make install' to install the programs and any data files and documentation. - 5. You can remove the program binaries and object files from the - source code directory by typing `make clean'. To also remove the - files that `configure' created (so you can compile the package for - a different kind of computer), type `make distclean'. There is - also a `make maintainer-clean' target, but that is intended mainly - for the package's developers. If you use it, you may have to get - all sorts of other programs in order to regenerate files that came - with the distribution. + 5. You can remove the program binaries and object files by deleting + all files from the `build' directory. In case you did not used a + dedicated build directory but build the software directly in the + source tree, you can remove the program binaries and object files + from the source code directory by typing `make clean'. To also + remove the files that `configure' created (so you can compile the + package for a different kind of computer), type `make distclean'. + There is also a `make maintainer-clean' target, but that is + intended mainly for the package's developers. If you use it, you + may have to get all sorts of other programs in order to + regenerate files that came with the distribution. Compilers and Options ===================== Some systems require unusual options for compilation or linking that the `configure' script does not know about. Run `./configure --help' for details on some of the pertinent environment variables. You can give `configure' initial values for configuration parameters by setting variables in the command line or in the environment. Here is an example: ./configure CC=c99 CFLAGS=-g LIBS=-lposix *Note Defining Variables::, for more details. Compiling For Multiple Architectures ==================================== You can compile the package for more than one kind of computer at the same time, by placing the object files for each architecture in their own directory. To do this, you can use GNU `make'. `cd' to the directory where you want the object files and executables to go and run the `configure' script. `configure' automatically checks for the source code in the directory that `configure' is in and in `..'. With a non-GNU `make', it is safer to compile the package for one architecture at a time in the source code directory. After you have installed the package for one architecture, use `make distclean' before reconfiguring for another architecture. Installation Names ================== By default, `make install' installs the package's commands under `/usr/local/bin', include files under `/usr/local/include', etc. You can specify an installation prefix other than `/usr/local' by giving `configure' the option `--prefix=PREFIX'. You can specify separate installation prefixes for architecture-specific files and architecture-independent files. If you pass the option `--exec-prefix=PREFIX' to `configure', the package uses PREFIX as the prefix for installing programs and libraries. Documentation and other data files still use the regular prefix. In addition, if you use an unusual directory layout you can give options like `--bindir=DIR' to specify different values for particular kinds of files. Run `configure --help' for a list of the directories you can set and what kinds of files go in them. If the package supports it, you can cause programs to be installed with an extra prefix or suffix on their names by giving `configure' the option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'. Optional Features ================= Some packages pay attention to `--enable-FEATURE' options to `configure', where FEATURE indicates an optional part of the package. They may also pay attention to `--with-PACKAGE' options, where PACKAGE is something like `gnu-as' or `x' (for the X Window System). The `README' should mention any `--enable-' and `--with-' options that the package recognizes. For packages that use the X Window System, `configure' can usually find the X include and library files automatically, but if it doesn't, you can use the `configure' options `--x-includes=DIR' and `--x-libraries=DIR' to specify their locations. Specifying the System Type ========================== There may be some features `configure' cannot figure out automatically, but needs to determine by the type of machine the package will run on. Usually, assuming the package is built to be run on the _same_ architectures, `configure' can figure that out, but if it prints a message saying it cannot guess the machine type, give it the `--build=TYPE' option. TYPE can either be a short name for the system type, such as `sun4', or a canonical name which has the form: CPU-COMPANY-SYSTEM where SYSTEM can have one of these forms: OS KERNEL-OS See the file `config.sub' for the possible values of each field. If `config.sub' isn't included in this package, then this package doesn't need to know the machine type. If you are _building_ compiler tools for cross-compiling, you should use the option `--target=TYPE' to select the type of system they will produce code for. If you want to _use_ a cross compiler, that generates code for a platform different from the build platform, you should specify the "host" platform (i.e., that on which the generated programs will eventually be run) with `--host=TYPE'. Sharing Defaults ================ If you want to set default values for `configure' scripts to share, you can create a site shell script called `config.site' that gives default values for variables like `CC', `cache_file', and `prefix'. `configure' looks for `PREFIX/share/config.site' if it exists, then `PREFIX/etc/config.site' if it exists. Or, you can set the `CONFIG_SITE' environment variable to the location of the site script. A warning: not all `configure' scripts look for a site script. Defining Variables ================== Variables not defined in a site shell script can be set in the environment passed to `configure'. However, some packages may run configure again during the build, and the customized values of these variables may be lost. In order to avoid this problem, you should set them in the `configure' command line, using `VAR=value'. For example: ./configure CC=/usr/local2/bin/gcc causes the specified `gcc' to be used as the C compiler (unless it is overridden in the site shell script). Unfortunately, this technique does not work for `CONFIG_SHELL' due to an Autoconf bug. Until the bug is fixed you can use this workaround: CONFIG_SHELL=/bin/bash /bin/bash ./configure CONFIG_SHELL=/bin/bash `configure' Invocation ====================== `configure' recognizes the following options to control how it operates. `--help' `-h' Print a summary of the options to `configure', and exit. `--version' `-V' Print the version of Autoconf used to generate the `configure' script, and exit. `--cache-file=FILE' Enable the cache: use and save the results of the tests in FILE, traditionally `config.cache'. FILE defaults to `/dev/null' to disable caching. `--config-cache' `-C' Alias for `--cache-file=config.cache'. `--quiet' `--silent' `-q' Do not print messages saying which checks are being made. To suppress all normal output, redirect it to `/dev/null' (any error messages will still be shown). `--srcdir=DIR' Look for the package's source code in directory DIR. Usually `configure' can determine that directory automatically. `configure' also accepts some other, not widely useful, options. Run `configure --help' for more details. - diff --git a/README b/README index 42eed238f..b9bf7805e 100644 --- a/README +++ b/README @@ -1,243 +1,246 @@ The GNU Privacy Guard ======================= Version 2.4 Copyright 1997-2019 Werner Koch Copyright 1998-2021 Free Software Foundation, Inc. Copyright 2003-2023 g10 Code GmbH * INTRODUCTION GnuPG is a complete and free implementation of the OpenPGP standard as defined by RFC4880 (also known as PGP). GnuPG enables encryption and signing of data and communication, and features a versatile key management system as well as access modules for public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available that make use of GnuPG. Starting with version 2 GnuPG provides support for S/MIME and Secure Shell in addition to OpenPGP. GnuPG is Free Software (meaning that it respects your freedom). It can be freely used, modified and distributed under the terms of the GNU General Public License. * BUILD INSTRUCTIONS GnuPG 2.4 depends on the following GnuPG related packages: npth (https://gnupg.org/ftp/gcrypt/npth/) libgpg-error (https://gnupg.org/ftp/gcrypt/libgpg-error/) libgcrypt (https://gnupg.org/ftp/gcrypt/libgcrypt/) libksba (https://gnupg.org/ftp/gcrypt/libksba/) libassuan (https://gnupg.org/ftp/gcrypt/libassuan/) You should get the latest versions of course, the GnuPG configure script complains if a version is not sufficient. Several other standard libraries are also required. The configure script prints diagnostic messages if one of these libraries is not available and a feature will not be available.. You also need the Pinentry package for most functions of GnuPG; however it is not a build requirement. Pinentry is available at https://gnupg.org/ftp/gcrypt/pinentry/ . After building and installing the above packages in the order as given above, you may continue with GnuPG installation (you may also just try to build GnuPG to see whether your already installed versions are sufficient). As with all packages, you just have to do - ./configure + mkdir build + cd build + ../configure make make check make install The "make check" is optional but highly recommended. To run even more tests you may add "--enable-all-tests" to the configure run. Before running the "make install" you might need to become root. If everything succeeds, you have a working GnuPG with support for OpenPGP, S/MIME, ssh-agent, and smartcards. In case of problem please ask on the gnupg-users@gnupg.org mailing list for advise. Instruction on how to build for Windows can be found in the file doc/HACKING in the section "How to build an installer for Windows". This requires some experience as developer. You may run gpgconf -L to view the directories used by GnuPG. To quickly build all required software without installing it, the Speedo method may be used: - make -f build-aux/speedo.mk native + cd build + make -f ../build-aux/speedo.mk native This method downloads all required libraries and does a native build of GnuPG to PLAY/inst/. GNU make is required and you need to set LD_LIBRARY_PATH to $(pwd)/PLAY/inst/lib to test the binaries. ** Specific build problems on some machines: *** Apple OSX 10.x using XCode On some versions the correct location of a header file can't be detected by configure. To fix that you should run configure like this ./configure gl_cv_absolute_stdint_h=/usr/include/stdint.h Add other options as needed. *** Systems without a full C99 compiler If you run into problems with your compiler complaining about dns.c you may use ./configure --disable-libdns Add other options as needed. * RECOMMENDATIONS ** Key database daemon Since version 2.3.0 it is possible to store the keys in an SQLite database instead of the keyring.kbx file. This is in particular useful for large keyrings or if many instances of gpg and gpgsm may run concurrently. This is implemented using another daemon process, the "keyboxd". To enable the use of the keyboxd put the option "use-keyboxd" into the configuration file ~/.gnupg/common.conf or the global /etc/gnupg/common.conf. See also doc/examples/common.conf. Only public keys and X.509 certificates are managed by the keyboxd; private keys are still stored as separate files. Note that there is no automatic migration; if the use-keyboxd option is enabled keys are not taken from pubring.kbx. To migrate existing keys to the keyboxd do this: 1. Disable the keyboxd (remove use-keyboxd from common.conf) 2. Export all public keys gpg --export --export-options backup > allkeys.gpg gpgsm --export --armor > allcerts.gpg 3. Enable the keyboxd (add use-keyboxd to common.conf) 4. Import all public keys gpg --import --import-options restore < allkeys.gpg gpgsm --import < allcerts.crt ** Socket directory GnuPG uses Unix domain sockets to connect its components (on Windows an emulation of these sockets is used). Depending on the type of the file system, it is sometimes not possible to use the GnuPG home directory (i.e. ~/.gnupg) as the location for the sockets. To solve this problem GnuPG prefers the use of a per-user directory below the the /run (or /var/run) hierarchy for the sockets. It is thus suggested to create per-user directories on system or session startup. For example, the following snippet can be used in /etc/rc.local to create these directories: [ ! -d /run/user ] && mkdir /run/user awk -F: = 1000 && $3 < 65000 {print $3}' \ | ( while read uid rest; do if [ ! -d "/run/user/$uid" ]; then mkdir /run/user/$uid chown $uid /run/user/$uid chmod 700 /run/user/$uid fi done ) * DOCUMENTATION The complete documentation is in the texinfo manual named `gnupg.info'. Run "info gnupg" to read it. If you want a a printable copy of the manual, change to the "doc" directory and enter "make pdf" For a HTML version enter "make html" and point your browser to gnupg.html/index.html. Standard man pages for all components are provided as well. An online version of the manual is available at [[https://gnupg.org/documentation/manuals/gnupg/]] . A version of the manual pertaining to the current development snapshot is at [[https://gnupg.org/documentation/manuals/gnupg-devel/]] . * Using the legacy version GnuPG 1.4 The 1.4 version of GnuPG is only intended to allow decryption of old data material using legacy keys which are not anymore supported by GnuPG 2.x. To install both versions alongside, it is suggested to rename the 1.4 version of "gpg" to "gpg1" as well as the corresponding man page. Newer releases of the 1.4 branch will likely do this by default. * HOW TO GET MORE INFORMATION A description of new features and changes since version 2.1 can be found in the file "doc/whats-new-in-2.1.txt" and online at "https://gnupg.org/faq/whats-new-in-2.1.html" . The primary WWW page is "https://gnupg.org" The primary FTP site is "https://gnupg.org/ftp/gcrypt/" See [[https://gnupg.org/download/mirrors.html]] for a list of mirrors and use them if possible. You may also find GnuPG mirrored on some of the regular GNU mirrors. We have some mailing lists dedicated to GnuPG: gnupg-announce@gnupg.org For important announcements like new versions and such stuff. This is a moderated list and has very low traffic. Do not post to this list. gnupg-users@gnupg.org For general user discussion and help. gnupg-devel@gnupg.org GnuPG developers main forum. You subscribe to one of the list by sending mail with a subject of "subscribe" to x-request@gnupg.org, where x is the name of the mailing list (gnupg-announce, gnupg-users, etc.). See https://gnupg.org/documentation/mailing-lists.html for archives of the mailing lists. Please direct bug reports to [[https://bugs.gnupg.org]] or post them direct to the mailing list . Please direct questions about GnuPG to the users mailing list or one of the PGP newsgroups; please do not direct questions to one of the authors directly as we are busy working on improvements and bug fixes. The mailing lists are watched by the authors and we try to answer questions as time allows us. Commercial grade support for GnuPG is available; for a listing of offers see https://gnupg.org/service.html . Maintaining and improving GnuPG requires a lot of time. Since 2001, g10 Code GmbH, a German company owned and headed by GnuPG's principal author Werner Koch, is bearing the majority of these costs. # This file is Free Software; as a special exception the authors gives # unlimited permission to copy and/or distribute it, with or without # modifications, as long as this notice is preserved. For conditions # of the whole package, please see the file COPYING. This file is # distributed in the hope that it will be useful, but WITHOUT ANY # WARRANTY, to the extent permitted by law; without even the implied # warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. # # Local Variables: # mode:org # End: