From 904936789b77a44082b8610d7f85d8de84447245 Mon Sep 17 00:00:00 2001 From: Andrew Toskin Date: Wed, 9 Aug 2017 00:46:12 -0700 Subject: [PATCH 1/4] Clarify dependencies: required vs optional, and build vs runtime. A first pass at updating the dependency documentation, based on the discussion in this thread: https://github.com/fish-shell/fish-shell/issues/2062 --- README.md | 43 +++++++++++++++++++++---------------------- 1 file changed, 21 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 24993bc81..f66ac8de4 100644 --- a/README.md +++ b/README.md @@ -13,17 +13,32 @@ Detailed user documentation is available by running `help` within fish, and also ## Building -fish requires a C++11 compiler. It builds successfully with g++ 4.8 or later, or with clang 3.3 or later. +### Dependencies -fish can be built using autotools or Xcode. autoconf 2.60 or later, as well as automake 1.13 or later, are required to build from git versions. These are not required to build from released tarballs. +Compiling fish requires: -fish depends on a curses implementation, such as ncurses. The headers and libraries are required for building. +* a C++11 compiler. It builds successfully with g++ 4.8 or later, or with clang 3.3 or later. fish can be built using autotools or Xcode. autoconf 2.60 or later, as well as automake 1.13 or later, are required to build from git versions, but these are not required to build from the officially released tarballs. +* the headers and libraries of a curses implementation such as ncurses. +* gettext, for translation support. +* Doxygen 1.8.7 or newer, for building the documentation. -fish requires PCRE2 due to the regular expression support contained in the `string` builtin. A copy is included with the source code, and will be used automatically if it does not already exist on your system. +At runtime, fish requires: -fish requires gettext for translation support. +* a curses implementation, such as ncurses. +* gettext, if you need the localizations. +* PCRE2, due to the regular expression support contained in the `string` builtin. A copy is included with the source code, and will be used automatically if it does not already exist on your system. +* a number of common UNIX utilities: coreutils (at least ls, seq, rm, mktemp), hostname, grep, awk, sed, and getopt. +* bc, the "basic calculator" program. -Building the documentation requires Doxygen 1.8.7 or newer. +Optional functionality should degrade gracefully. If fish ever threw an error about missing dependencies for an optional feature, it would be a bug in fish and should be reported on our GitHub. Optional features and dependencies include: + +* fish's builtin `test` syntax, which requires `diff` and `expect`. You don't need these, though, if you don't want to use our tests. +* dynamically generating usage tips for builtin functions, which requires man, apropos, nroff, and ul. +* manual page parsing for auto-completion for external commands, which also requires the above man tools, plus Python 2.6+ or Python 3.3+. Python 2 will also need the backports.lzma package; Python 3.3+ should include the required module by default. +* the web configuration tool, which requires Python 2.6+ or 3.3+. +* the fish_clipboard_* functions (bound to \cv and \cx), which require xsel or pbcopy/pbpaste. + +fish can also show VCS information in the prompt, when the current working directory is in a VCS-tracked project. This is one of the weakest dependencies, though: if you don't use git, you don't need git information in the prompt, and if you do use git, you already have it. ### Autotools Build @@ -55,22 +70,6 @@ On RedHat, CentOS, or Amazon EC2: sudo yum install ncurses-devel -## Runtime Dependencies - -fish requires a curses implementation, such as ncurses, to run. - -fish requires PCRE2 due to the regular expression support contained in the `string` builtin. A bundled version will be compiled in automatically at build time if required. - -fish requires a number of utilities to operate, which should be present on any Unix, GNU/Linux or OS X system. These include (but are not limited to) hostname, grep, awk, sed, and getopt. fish also requires the bc program. - -Translation support requires the gettext program. - -Usage output for builtin functions is generated on-demand from the installed manpages using `nroff` and `ul`. - -Some optional features of fish, such as the manual page completion parser and the web configuration tool, require Python. - -In order to generate completions from man pages compressed with either lzma or xz, you may need to install an extra Python package. Python versions prior to 2.6 are not supported. To process lzma-compresed manpages, backports.lzma is needed for Python 3.2 or older. From version 3.3 onwards, Python already includes the required module. - ## Packages for Linux Instructions on how to find builds for several Linux distros are at From 101926a8e8e3a131d50128362be6fb303638e06f Mon Sep 17 00:00:00 2001 From: Andrew Toskin Date: Thu, 10 Aug 2017 23:03:51 -0700 Subject: [PATCH 2/4] Clarify notes on dependency errors, tests, and VCS integration. An optional feature that suggests you install Python is okay; core-dumping is not. The note on tests was about fish development tests, not the `test` builtin for conditional syntax. Specifically mention git, hg, and svn in the VCS section. --- CONTRIBUTING.md | 2 ++ README.md | 5 ++--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 373c3dc9a..a01431df2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,6 +31,8 @@ To make linting the code easy there are two make targets: `lint` and `lint-all`. Fish has custom cppcheck rules in the file `.cppcheck.rule`. These help catch mistakes such as using `wcwidth()` rather than `fish_wcwidth()`. Please add a new rule if you find similar mistakes being made. +Fish also depends on `diff` and `expect` for its tests. + ### Dealing With Lint Warnings You are strongly encouraged to address a lint warning by refactoring the code, changing variable names, or whatever action is implied by the warning. diff --git a/README.md b/README.md index f66ac8de4..c98751418 100644 --- a/README.md +++ b/README.md @@ -30,15 +30,14 @@ At runtime, fish requires: * a number of common UNIX utilities: coreutils (at least ls, seq, rm, mktemp), hostname, grep, awk, sed, and getopt. * bc, the "basic calculator" program. -Optional functionality should degrade gracefully. If fish ever threw an error about missing dependencies for an optional feature, it would be a bug in fish and should be reported on our GitHub. Optional features and dependencies include: +Optional functionality should degrade gracefully. (If fish ever threw a syntax error or a core dump due to missing dependencies for an optional feature, it would be a bug in fish and should be reported on our GitHub.) Optional features and dependencies include: -* fish's builtin `test` syntax, which requires `diff` and `expect`. You don't need these, though, if you don't want to use our tests. * dynamically generating usage tips for builtin functions, which requires man, apropos, nroff, and ul. * manual page parsing for auto-completion for external commands, which also requires the above man tools, plus Python 2.6+ or Python 3.3+. Python 2 will also need the backports.lzma package; Python 3.3+ should include the required module by default. * the web configuration tool, which requires Python 2.6+ or 3.3+. * the fish_clipboard_* functions (bound to \cv and \cx), which require xsel or pbcopy/pbpaste. -fish can also show VCS information in the prompt, when the current working directory is in a VCS-tracked project. This is one of the weakest dependencies, though: if you don't use git, you don't need git information in the prompt, and if you do use git, you already have it. +fish can also show VCS information in the prompt, when the current working directory is in a VCS-tracked project, with support for Git, Mercurial, and Subversion. This is one of the weakest dependencies, though: if you don't use git, for example, you don't need git information in the prompt, and if you do use git, you already have it. Similarly, fish comes with a variety of auto-completion scripts to help with command-line usage of a variety of applications; these scripts call the application in question, but you should only need these applications if you use them. ### Autotools Build From 47a768ceeaef1d702624802d83338edbcc0f377c Mon Sep 17 00:00:00 2001 From: Andrew Toskin Date: Sat, 12 Aug 2017 00:50:45 -0700 Subject: [PATCH 3/4] Really spell out the last of the required UNIX utilities. Finishing the job started in Pull Request #4301 Thanks to @faho for filtering and sorting my giant list of detected possible commands. --- README.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c98751418..b39b4908a 100644 --- a/README.md +++ b/README.md @@ -24,10 +24,20 @@ Compiling fish requires: At runtime, fish requires: -* a curses implementation, such as ncurses. +* a curses implementation such as ncurses (which should provide the `tput` command). * gettext, if you need the localizations. * PCRE2, due to the regular expression support contained in the `string` builtin. A copy is included with the source code, and will be used automatically if it does not already exist on your system. -* a number of common UNIX utilities: coreutils (at least ls, seq, rm, mktemp), hostname, grep, awk, sed, and getopt. +* a number of common UNIX utilities: + * an awk implementation, such as gawk, mawk, etc + * coreutils --- at least basename, cat, cut, date, dircolors, dirname, ls, mkdir, mkfifo, mktemp, rm, seq, sort, stat, stty, tail, tr, tty, uname, uniq, wc, whoami + * find + * getent (part of glibc) + * getopt + * grep + * hostname + * kill + * ps + * sed * bc, the "basic calculator" program. Optional functionality should degrade gracefully. (If fish ever threw a syntax error or a core dump due to missing dependencies for an optional feature, it would be a bug in fish and should be reported on our GitHub.) Optional features and dependencies include: From e80e9c6b068a7824a0ef4232fe281429b485e415 Mon Sep 17 00:00:00 2001 From: Andrew Toskin Date: Sat, 12 Aug 2017 22:40:48 -0700 Subject: [PATCH 4/4] getopt isn't used anymore, and getent itself is optional. getopt doesn't work very well in the BSDs, and getent has plenty of fallbacks to replace it when it's not available. --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index b39b4908a..4c36b4e35 100644 --- a/README.md +++ b/README.md @@ -31,8 +31,6 @@ At runtime, fish requires: * an awk implementation, such as gawk, mawk, etc * coreutils --- at least basename, cat, cut, date, dircolors, dirname, ls, mkdir, mkfifo, mktemp, rm, seq, sort, stat, stty, tail, tr, tty, uname, uniq, wc, whoami * find - * getent (part of glibc) - * getopt * grep * hostname * kill