From e27855b22569523a8f9ce4f417d90a0788acf1bd Mon Sep 17 00:00:00 2001 From: Andrew Toskin Date: Fri, 11 Aug 2017 03:52:38 -0700 Subject: [PATCH 1/4] Clarify dependencies: required vs optional, and build vs runtime. (#4301) * 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 * 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 | 42 ++++++++++++++++++++---------------------- 2 files changed, 22 insertions(+), 22 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 24993bc81..c98751418 100644 --- a/README.md +++ b/README.md @@ -13,17 +13,31 @@ 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 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: + +* 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, 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 @@ -55,22 +69,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 4dbb274d8af6991200939797abe62247933485bc Mon Sep 17 00:00:00 2001 From: Fabian Homborg Date: Fri, 11 Aug 2017 15:05:28 +0200 Subject: [PATCH 2/4] Clarify docs on $status with and/or/begin/end See #4311. --- doc_src/and.txt | 2 +- doc_src/begin.txt | 2 +- doc_src/end.txt | 2 +- doc_src/or.txt | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc_src/and.txt b/doc_src/and.txt index ed56da62d..2670a35e1 100644 --- a/doc_src/and.txt +++ b/doc_src/and.txt @@ -11,7 +11,7 @@ COMMAND1; and COMMAND2 `and` statements may be used as part of the condition in an `if` or `while` block. See the documentation for `if` and `while` for examples. -`and` does not change the current exit status. The exit status of the last foreground command to exit can always be accessed using the $status variable. +`and` does not change the current exit status itself, but the command it runs most likely will. The exit status of the last foreground command to exit can always be accessed using the $status variable. \subsection and-example Example diff --git a/doc_src/begin.txt b/doc_src/begin.txt index 6d18a6061..374fc78ce 100644 --- a/doc_src/begin.txt +++ b/doc_src/begin.txt @@ -13,7 +13,7 @@ The block is unconditionally executed. `begin; ...; end` is equivalent to `if tr `begin` is used to group a number of commands into a block. This allows the introduction of a new variable scope, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like `and`. -`begin` does not change the current exit status. +`begin` does not change the current exit status itself. After the block has completed, `$status` will be set to the status returned by the most recent command. \subsection begin-example Example diff --git a/doc_src/end.txt b/doc_src/end.txt index 76cbe3603..2b035930c 100644 --- a/doc_src/end.txt +++ b/doc_src/end.txt @@ -16,4 +16,4 @@ switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end For more information, read the documentation for the block constructs, such as `if`, `for` and `while`. -The `end` command does not change the current exit status. +The `end` command does not change the current exit status. Instead, the status after it will be the status returned by the most recent command. diff --git a/doc_src/or.txt b/doc_src/or.txt index 97707e064..40b6bfcc7 100644 --- a/doc_src/or.txt +++ b/doc_src/or.txt @@ -12,7 +12,7 @@ COMMAND1; or COMMAND2 `or` statements may be used as part of the condition in an `and` or `while` block. See the documentation for `if` and `while` for examples. -`or` does not change the current exit status. The exit status of the last foreground command to exit can always be accessed using the $status variable. +`or` does not change the current exit status itself, but the command it runs most likely will. The exit status of the last foreground command to exit can always be accessed using the $status variable. \subsection or-example Example From 219c7ec81212752d755a33beccb891f863e427b7 Mon Sep 17 00:00:00 2001 From: Fabian Homborg Date: Fri, 11 Aug 2017 18:27:58 +0200 Subject: [PATCH 3/4] help: Fix error if no argument is given --- share/functions/help.fish | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/share/functions/help.fish b/share/functions/help.fish index a31d6af04..d8c4f26c6 100644 --- a/share/functions/help.fish +++ b/share/functions/help.fish @@ -100,7 +100,7 @@ function help --description 'Show help for the fish shell' case "*" # If $fish_help_item is empty, this will fail, # and $fish_help_page will end up as index.html - if type -q -f $fish_help_item + if type -q -f "$fish_help_item" # Prefer to use fish's man pages, to avoid # the annoying useless "builtin" man page bash # installs on OS X From 67f7e53237c280f16b54ace4061486d3aefc30ba Mon Sep 17 00:00:00 2001 From: Mahmoud Al-Qudsi Date: Fri, 11 Aug 2017 13:51:28 -0500 Subject: [PATCH 4/4] Ignore more invalid arguments from parsed man pages Specifically closes #4313. Not being as agressive in what we ignore/blacklist, but can be revisited easily in the future to add more characters to the argument blacklist. --- share/tools/create_manpage_completions.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/share/tools/create_manpage_completions.py b/share/tools/create_manpage_completions.py index 0eb4045bc..598cff0a2 100755 --- a/share/tools/create_manpage_completions.py +++ b/share/tools/create_manpage_completions.py @@ -131,11 +131,12 @@ def built_command(options, description): fish_options = [] for optionstr in man_optionlist: option = re.sub(r"(\[.*\])", "", optionstr) - option = option.strip(" \t\n[]()") + option = option.strip(" \t\r\n[](){}.,:!") # Skip some problematic cases if option in ['-', '--']: continue + if any(c in "{}()" for c in option): continue if option.startswith('--'): # New style long option (--recursive)