[sdk/kde-builder/fish_completion] /: Fish shell completion
Finley Watson <[email protected]>
| Newsgroups | gmane.comp.kde.cvs |
|---|---|
| Message-ID | <[email protected]> |
Git commit 62593382473955ba71a9569633f2f35250dceb9f by Finley Watson. Committed on 20/07/2026 at 15:10. Pushed by finw into branch 'fish_completion'. Fish shell completion Add completion file for the Fish shell, and basic documentation. This follows how the Bash and Zsh shells approach caching of projects and binaries with cache files with an expiration date. I've added URLs to the relevant docs section for each command line option in the comments, hopefully these can be kept in sync. A +716 -0 data/completions/fish/kde-builder.fish A +62 -0 doc/getting-started/fish-completion-setup.md M +1 -0 doc/getting-started/index.md https://invent.kde.org/sdk/kde-builder/-/commit/62593382473955ba71a9569633f2f35250dceb9f diff --git a/data/completions/fish/kde-builder.fish b/data/completions/fish/kde-builder.fish new file mode 100644 index 00000000..f1bca56b --- /dev/null +++ b/data/completions/fish/kde-builder.fish @@ -0,0 +1,716 @@ +#!/usr/bin/env fish +# KDE Builder: fish completion +# +# SPDX-FileCopyrightText: 2026 Finley Watson <[email protected]> +# +# SPDX-License-Identifier: GPL-2.0-or-later + +# CACHING + +# Generate the list of projects and groups for completions. This uses caching for speed. +set --local projects +set --local groups +set --local projects_and_groups + +set --local run_argument_completions + +# Find the cache dir. +set --local cache_dir $HOME/.cache/fish +if set --query XDG_CACHE_HOME + set cache_dir $XDG_CACHE_HOME/fish +end +# Create cache directory if it doesn't exist +mkdir -p "$cache_dir" 2>/dev/null + +set --local cache_projects_file "$cache_dir/kde_builder_projects" +set --local cache_groups_file "$cache_dir/kde_builder_groups" +set --local cache_projects_and_groups_file "$cache_dir/kde_builder_projects_and_groups" +set --local cache_installed_projects_file "$cache_dir/kde_builder_installed_projects" +set --local cache_projects_and_groups_timeout 604800 # 1 week in seconds +set --local cache_installed_projects_timeout 300 # 5 minutes in seconds + +# 5-minute cache just for binaries. +if test -f "$cache_installed_projects_file" + set --local cache_age + if test -n "(command -v stat)" + # Try GNU stat first, then BSD stat + set cache_age (math (date +%s) \ + - (stat -c %Y "$cache_installed_projects_file" 2>/dev/null \ + || stat -f %m "$cache_installed_projects_file" 2>/dev/null \ + || echo 0)) + else + # Force refresh if stat not available + set cache_age "$cache_installed_projects_timeout" + end + + if test "$cache_age" -lt "$cache_installed_projects_timeout" + # Load the data from the cache. + set run_argument_completions (cat "$cache_installed_projects_file") + end +end + +# 1-week caching, tests against the file kde_builder_projects_and_groups only. +if test -f "$cache_projects_and_groups_file" + set --local cache_age + if test -n "(command -v stat)" + # Try GNU stat first, then BSD stat + set cache_age (math (date +%s) \ + - (stat -c %Y "$cache_projects_and_groups_file" 2>/dev/null \ + || stat -f %m "$cache_projects_and_groups_file" 2>/dev/null \ + || echo 0)) + else + # Force refresh if stat not available + set cache_age "$cache_projects_and_groups_timeout" + end + + if test "$cache_age" -lt "$cache_projects_and_groups_timeout" + # Load the data from the cache. + set projects (cat "$cache_projects_file") + set groups (cat "$cache_groups_file") + set projects_and_groups (cat "$cache_projects_and_groups_file") + end +end + +# Load the installed binary data on cache miss, and save to 5-min cache. +if test -z "$run_argument_completions" + # Config for $run_argument_completions + # + # The awk function string generates a lint that's not useful. + # @fish-lsp-disable-next-line + set --local kde_builder_binaries_path (awk -F: ' + /^[ ]+install-dir:/ { + path=$2; # Second part split by : + gsub(/^[ \t]+/, "", path); # Strip leading whitespace + gsub(/[ \t]*#.*$/, "", path); # Strip trailing whitespace and any comment + gsub(/^~/, ENVIRON["HOME"], path); # Convert tilde into absolute path + print path "/bin"; # Return the binary dir in the install dir + exit; # Only process the first instance of a match + }' $HOME/.config/kde-builder.yaml) + + set run_argument_completions (find $kde_builder_binaries_path -type f -exec basename {} \;) + + # Cache the data. + echo "$run_argument_completions" >"$cache_installed_projects_file" 2>/dev/null +end + +# Load the project and group data on cache miss, and save to 1-week cache. +if test -z "$projects_and_groups" + # Reload the data. + set --local projects_and_groups_query_output (kde-builder --no-metadata --query group --all-kde-projects --all-config-projects --log-level application=ERROR 2>/dev/null) + + # Parse the output into useful data. + if test -n "$projects_and_groups_query_output" + # Parse the query output and get the project name in each list entry, sort and remove duplicates. + set projects (string split -f1 ':' -- $projects_and_groups_query_output | sort -u) + # Parse the query output and get the group name in each list entry, sort and remove duplicates. + set groups (string split -f2 ':' -- $projects_and_groups_query_output | string trim | sort -u) + # Populate a mixed list of projects and groups, again sorted and deduped. + set projects_and_groups (printf '%s\n' $projects\n$groups | sort -u) + end + + # Cache the data. + echo "$projects" >"$cache_projects_file" 2>/dev/null + echo "$groups" >"$cache_groups_file" 2>/dev/null + echo "$projects_and_groups" >"$cache_projects_and_groups_file" 2>/dev/null +end + +# CONFIG AND SET-UP + +# Disable files by default in completions (certain arguments selectively enable this). +complete --command kde-builder --no-files + +# Generate some options used in specific completions. +set --local taskset_cpu_list_argument_completions (set --local cpu_cores (nproc) ; echo "auto" ; for i in (seq 1 $cpu_cores) ; echo 0-$i ; end) +set --local nice_argument_completions (for i in (seq 0 19) ; echo $i ; end) +set --local num_cores_argument_completions (set --local cpu_cores (nproc) ; echo "auto" ; for i in (seq 1 $cpu_cores) ; echo $i ; end) +set --local num_cores_low_mem_argument_completions "$num_cores_argument_completions" +set --local cmake_generator_argument_completions (echo "Ninja"; echo "Unix Makefiles") + +# Make all known projects available at any point in the arguments. +for project_name in $projects + complete --command kde-builder --arguments "$project_name" --description Project +end + +# Make all known groups available at any point in the arguments. +for group_name in $groups + complete --command kde-builder --arguments "$group_name" --description Group +end + +# COMMAND LINE OPTIONS + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-pretend +complete --command kde-builder --long pretend --short p \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Operate in 'dry run' mode" +complete --command kde-builder --long dry-run \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Operate in 'dry run' mode" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-include-dependencies +complete --command kde-builder --long include-dependencies --short d \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-include-dependencies -D --include-dependencies -d" \ + --description "Automatically build dependencies (KDE / Qt projects)" +complete --command kde-builder --long no-include-dependencies --short D \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --include-dependencies -d --no-include-dependencies -D " \ + --description "Do not build dependencies" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-ignore-projects +complete --command kde-builder --long ignore-projects --short ! --require-parameter --arguments "$projects_and_groups" \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Ignore the given projects" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-run +complete --command kde-builder --long run --require-parameter --no-files --arguments "$run_argument_completions" \ + --condition "not __fish_prev_arg_in --start-program" \ + --description "Run the given binary" +complete --command kde-builder --long start-program --require-parameter --no-files --arguments "$run_argument_completions" \ + --condition "not __fish_prev_arg_in --run" \ + --description "Run the given binary" +complete --command kde-builder --long fork --short f --require-parameter --arguments "$run_argument_completions" \ + --condition "__fish_prev_arg_in --run --start-program" \ + --description "Detach program process given by --run from current terminal" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-source-when-start-program +complete --command kde-builder --long source-when-start-program --force-files \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Run given shell file before launching project given by --run e.g. to set environment variables" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-revision +# NOTE: a revision ID follows, we don't offer completions for this though. +complete --command kde-builder --long revision --no-files \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Checkout specific revision" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-taskset-cpu-list +complete --command kde-builder --long taskset-cpu-list --arguments "$taskset_cpu_list_argument_completions" \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Limit CPU cores used" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-hold-performance-profile +complete --command kde-builder --long hold-performance-profile \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-hold-performance-profile" \ + --description "Try to switch system power profile to performance mode while building" +complete --command kde-builder --long no-hold-performance-profile \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --hold-performance-profile" \ + --description "Do not try to switch system power profile to performance mode while building" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-hold-work-branches +complete --command kde-builder --long hold-work-branches \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-hold-work-branches" \ + --description "Skip updating sources for projects with Git current branch starting with work/* or mr/*" +complete --command kde-builder --long no-hold-work-branches \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --hold-work-branches" \ + --description "Update sources for projects with Git current branch starting with work/* or mr/*" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-all-config-projects +complete --command kde-builder --long all-config-projects \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Operate on all projects defined in user config" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-all-kde-projects +complete --command kde-builder --long all-kde-projects \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Operate on all known projects defined in metadata" + +# NOTE: It's not sensibly possible to provide completions for YAML options. +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-option-name +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-set-project-option-value + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-resume-from +complete --command kde-builder --long from --short f --require-parameter --arguments "$projects" \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_prev_arg_in --run" \ + --description "Resume from given project. Do not supply other project names in the command line" +complete --command kde-builder --long resume-from --require-parameter --arguments "$projects" \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Resume from given project. Do not supply other project names in the command line" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-resume-after +complete --command kde-builder --long after --short a --require-parameter --arguments "$projects" \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Resume after given project. Do not supply other project names in the command line" +complete --command kde-builder --long resume-after --require-parameter --arguments "$projects" \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Resume after given project. Do not supply other project names in the command line" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-resume +complete --command kde-builder --long resume \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Resume previously failed build from the project that failed" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-resume-refresh-build-first +complete --command kde-builder --long resume-refresh-build-first --short R \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Alias for --resume --refresh-build-first" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-stop-before +complete --command kde-builder --long stop-before --require-parameter --arguments "$projects" \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Stop normal build before the given project would have been built" +complete --command kde-builder --long until --require-parameter --arguments "$projects" \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Stop normal build before the given project would have been built" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-stop-after +complete --command kde-builder --long stop-after --require-parameter --arguments "$projects" \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Stop normal build after the given project builds" +complete --command kde-builder --long to --require-parameter --arguments "$projects" \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Stop normal build after the given project builds" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-stop-on-failure +complete --command kde-builder --long stop-on-failure \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-stop-on-failure" \ + --description "Abort as soon as failure occurs" +complete --command kde-builder --long no-stop-on-failure \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --stop-on-failure" \ + --description "Continue building remaining projects even is some fail" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-rebuild-failures +complete --command kde-builder --long rebuild-failures \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Build only projects that failed to build in a previous kde-builder run" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-query +complete --command kde-builder --long query --arguments "source-dir build-dir install-dir project-path branch group build-system project info" \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Query a parameter of the projects in the build list and output the result to screen" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-dependency-tree +complete --command kde-builder --long dependency-tree \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Print dependency tree" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-dependency-tree-fullpath +complete --command kde-builder --long dependency-tree-fullpath \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Print dependency tree with full paths" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-list-installed +complete --command kde-builder --long list-installed \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Print installed projects and exit" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-no-metadata +complete --command kde-builder --long no-metadata --short M \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --metadata-only" \ + --description "Skip project metadata update. Source updates will still occur" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-no-src +complete --command kde-builder --long no-src --short S \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_any_arg_in --src-only -s" \ + --description "Skip project source update" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-no-build +complete --command kde-builder --long no-build \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_any_arg_in --build-only --install-only" \ + --description "Skip build phase. Currently equivalent to --src-only" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-no-install +complete --command kde-builder --long no-install \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_any_arg_in --install-only" \ + --description "Skip the install phase" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-metadata-only +complete --command kde-builder --long metadata-only \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-metadata" \ + --description "Only perform the metadata download process" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-src-only +complete --command kde-builder --long src-only --short s \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_any_arg_in --build-only --install-only --no-src -S" \ + --description "Only perform the source update" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-build-only +complete --command kde-builder --long build-only \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_any_arg_in --no-build --install-only --src-only -s" \ + --description "Do not update source before building, do not install" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-install-only +complete --command kde-builder --long install-only \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_any_arg_in --build-only --no-build --no-install --src-only -s" \ + --description "Install projects listed in log/latest/status-list.log, or from command line if given" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-uninstall +complete --command kde-builder --long uninstall \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Immediately attempt to uninstall given projects, relies on 'make uninstall'" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-build-system-only +complete --command kde-builder --long build-system-only \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Build, but do not run 'make' or attempt to install" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-install-login-session-only +complete --command kde-builder --long install-login-session-only \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Can be used to only invoke the session installation script, so you can bypass any project update/build phases" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-refresh-build +complete --command kde-builder --long refresh-build --short r \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Reconfigure project and build from a clean state" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-refresh-build-first +complete --command kde-builder --long refresh-build-first \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Enable --refresh-build for the first project in the list to build, useful with --resume" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-reconfigure +complete --command kde-builder --long reconfigure \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Run 'cmake' or 'configure' without cleaning the build directory" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-install-dir +complete --command kde-builder --long install-dir --force-files \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Change the directory where projects will be installed to" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-generate-clion-project-config +complete --command kde-builder --long generate-clion-project-config --no-files \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-generate-clion-project-config" \ + --description "Generate an .idea directory with config for building and debugging in CLion" +complete --command kde-builder --long no-generate-clion-project-config \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --generate-clion-project-config" \ + --description "Do not generate an .idea directory with config for building and debugging in CLion" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-generate-vscode-project-config +complete --command kde-builder --long generate-vscode-project-config \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-generate-vscode-project-config" \ + --description "Generate a .vscode directory with config for building and debugging in VSCode" +complete --command kde-builder --long no-generate-vscode-project-config \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --generate-vscode-project-config" \ + --description "Do not generate a .vscode directory with config for building and debugging in VSCode" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-generate-clion-project-config +complete --command kde-builder --long generate-qtcreator-project-config \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-generate-qtcreator-project-config" \ + --description "Generate a .qtcreator directory with files that can be used for copying to the Qt Creator configuration for building and debugging" +complete --command kde-builder --long no-generate-qtcreator-project-config \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --generate-qtcreator-project-config" \ + --description "Do not generate a .qtcreator directory with files that can be used for copying to the Qt Creator configuration for building and debugging" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-async +complete --command kde-builder --long async \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-async" \ + --description "Update source code and build projects at the same time" +complete --command kde-builder --long no-async \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --async" \ + --description "Do not update source code and build projects at the same time" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-color +complete --command kde-builder --long color \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-color and not __fish_seen_argument --no-colorful-output" \ + --description "Enable colorful output" +complete --command kde-builder --long colorful-output \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-color and not __fish_seen_argument --no-colorful-output" \ + --description "Enable colorful output" +complete --command kde-builder --long no-color \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --color and not __fish_seen_argument --colorful-output" \ + --description "Disable colorful output" +complete --command kde-builder --long no-colorful-output \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --color and not __fish_seen_argument --colorful-output" \ + --description "Disable colorful output" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-debug +complete --command kde-builder --long debug \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Enable DEBUG level of every logger of kde-builder" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-nice +complete --command kde-builder --long nice --arguments "$nice_argument_completions" \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Adjust CPU priority, 0 is highest priority, 19 is lowest" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-rc-file +complete --command kde-builder --long rc-file --require-parameter --force-files \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Path to the config file used by kde-builder" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-log-level +# NOTE: correct use is e.g. --log-level ide_project_configs=DEBUG +# but we do not provide completions for loggers. +complete --command kde-builder --long log-level --no-files \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Set the verbosity level of an internal debugger" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-check-self-updates +complete --command kde-builder --long check-self-updates \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-check-for-updates" \ + --description "Check for updates once a week" +complete --command kde-builder --long no-check-self-updates \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --check-for-updates" \ + --description "Do not check for updates once a week" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-initial-setup +complete --command kde-builder --long initial-setup \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Perform a one-time initial set up to prepare the system for kde-builder to operate and KDE software to run" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-install-distro-packages +complete --command kde-builder --long install-distro-packages \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Install necessary distro packages for kde-builder and newly-installed KDE software" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-generate-config +complete --command kde-builder --long generate-config \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Generate the kde-builder configuration file" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-prompt-answer +complete --command kde-builder --long prompt-answer \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Prevent interactive prompts, use given value as prompt answer" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-self-update +complete --command kde-builder --long self-update \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Update kde-builder" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-version +complete --command kde-builder --long version \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Display the program version" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-help +complete --command kde-builder --long help \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Display help" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-show-info +complete --command kde-builder --long show-info \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Display info about kde-builder and the system e.g. for bug reports" + +# https://kde-builder.kde.org/en/cmdline/supported-cmdline-params.html#cmdline-show-options-specifiers +complete --command kde-builder --long show-options-specifiers \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Print specifier lines for all supported command line options, e.g. for generating shell completions" + +# CONFIGURATION OPTIONS + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-disable-agent-check +complete --command kde-builder --long disable-agent-check \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-disable-agent-check" \ + --description "Try and prevent SSH from asking for a passphrase for every project" +complete --command kde-builder --long no-disable-agent-check \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --disable-agent-check" \ + --description "Let SSH ask for a passphrase for every project" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-install-login-session +complete --command kde-builder --long install-login-session \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-install-login-session" \ + --description "Invoke session installation script from plasma-workspace" +complete --command kde-builder --long no-install-login-session \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --install-login-session" \ + --description "Do not invoke session installation script" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-libpath +complete --command kde-builder --long libpath --force-files --require-parameter \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Set environment variable LD_LIBRARY_PATH while building" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-num-cores +complete --command kde-builder --long num-cores --require-parameter --no-files --arguments "$num_cores_argument_completions" \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "How many CPU cores to build projects with" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-num-cores-low-mem +complete --command kde-builder --long num-cores-low-mem \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "How many CPU cores to build large / intensive projects with, to avoid running out of RAM" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-persistent-data-file +complete --command kde-builder --long persistent-data-file --require-parameter --force-files \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Manually set where kde-builder stores its persistent date" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-binpath +complete --command kde-builder --long binpath --force-files --require-parameter \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Set environment variable PATH while building" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-branch +complete --command kde-builder --long branch \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Checkout the specified branch instead of the default branch" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-branch-group +complete --command kde-builder --long branch-group \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "kde-builder will determine the actual branch to use based on rules encoded by the KDE developers" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-build-dir +complete --command kde-builder --long build-dir --force-files \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Manually set where built project are saved. Relative paths are relative to source directory" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-cmake-generator +complete --command kde-builder --long cmake-generator --require-parameter --no-files --arguments "$cmake_generator_argument_completions" \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "The generator that will be used by CMake" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-cmake-toolchain +complete --command kde-builder --long cmake-toolchain --require-parameter --force-files \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "A toolchain file to be used by CMake" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-cmake-options +complete --command kde-builder --long cmake-options --no-files \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Pass flags to CMake." + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-compile-commands-export +complete --command kde-builder --long compile-commands-export \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-compile-commands-export" \ + --description "Generate compile_commands.json in the build directory" +complete --command kde-builder --long no-compile-commands-export \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --compile-commands-export" \ + --description "Do not generate compile_commands.json in the build directory" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-compile-commands-linking +complete --command kde-builder --long compile-commands-linking \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-compile-commands-linking" \ + --description "Make a symbolic link in the source directory pointing to compile_commands.json in the build directory" +complete --command kde-builder --long no-compile-commands-linking \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --compile-commands-linking" \ + --description "Do not make a symbolic link in the source directory pointing to compile_commands.json in the build directory" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-configure-flags +complete --command kde-builder --long configure-flags \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Pass flags to ./configure when creating project build system." + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-custom-build-command +complete --command kde-builder --long custom-build-command \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Perform a build process with the given command" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-cxxflags +complete --command kde-builder --long cxxflags \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Specify flags to use for building the project" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-dest-dir +complete --command kde-builder --long dest-dir --require-parameter --force-files \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Change the name of a project on disk" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-git-user +complete --command kde-builder --long git-user \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Set identity in newly downloaded projects. Provide in the form 'User Name <[email protected]>'" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-directory-layout +complete --command kde-builder --long directory-layout --require-parameter --arguments "flat invent metadata" \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Dictate structure of source and build directories for projects" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-libname +complete --command kde-builder --long libname --require-parameter --no-files --arguments "lib lib64" \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Set installed library directory name inside install dir and Qt install dir" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-log-dir +complete --command kde-builder --long log-dir --require-parameter --force-files \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Set the log file directory" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-make-install-prefix +complete --command kde-builder --long make-install-prefix --no-files \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Precede `make install` with the given space-separated command" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-make-options +complete --command kde-builder --long make-options \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Pass command line options to `make`" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-meson-options +complete --command kde-builder --long meson-options \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Pass command line options to `meson`" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-ninja-options +complete --command kde-builder --long ninja-options \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Pass command line options to `ninja`" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-override-build-system +complete --command kde-builder --long override-build-system --require-parameter --no-files --arguments "KDE Qt qmake generic autotools meson" \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Set the appropriate build system for a project" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-purge-old-logs +complete --command kde-builder --long purge-old-logs \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-purge-old-logs" \ + --description "Delete old logs" +complete --command kde-builder --long no-purge-old-logs \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --purge-old-logs" \ + --description "Do not delete old logs" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-qmake-options +complete --command kde-builder --long qmake-options \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Pass given options to `qmake`" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-qt-install-dir +complete --command kde-builder --long qt-install-dir --require-parameter --force-files \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Where to install Qt projects after build" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-remove-after-install +complete --command kde-builder --long remove-after-install --require-parameter --no-files --arguments "none builddir all" \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Delete source / build directories after build is complete" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-repository +complete --command kde-builder --long repository \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Specify the Git repository to download the source code of the project" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-revision +complete --command kde-builder --long revision --require-parameter --no-files \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Force source update to the exact revision given" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-run-tests +complete --command kde-builder --long run-tests \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-run-tests" \ + --description "Build with BUILD_TESTING on and run tests after building" +complete --command kde-builder --long no-run-tests \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --run-tests" \ + --description "Do not run tests after building" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-set-env +complete --command kde-builder --long set-env \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Accepts a dictionary where key is each environment variable you want to set" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-source-dir +complete --command kde-builder --long source-dir --require-parameter --force-files \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Set where projects source are saved to" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-tag +complete --command kde-builder --long tag --no-files \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Download a specific release of a project" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-use-clean-install +complete --command kde-builder --long use-clean-install \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --no-use-clean-install" \ + --description "Run `make uninstall` directly before running `make install`" +complete --command kde-builder --long no-use-clean-install \ + --condition "not __fish_prev_arg_in --run --start-program and not __fish_seen_argument --use-clean-install" \ + --description "Do not run `make uninstall` directly before running `make install`" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-filter-out-phases +complete --command kde-builder --long filter-out-phases \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Remove given space-separated phases" + +# https://kde-builder.kde.org/en/configuration/conf-options-table.html#conf-use-projects +complete --command kde-builder --long use-projects \ + --condition "not __fish_prev_arg_in --run --start-program" \ + --description "Update and build the projects in the order given" diff --git a/doc/getting-started/fish-completion-setup.md b/doc/getting-started/fish-completion-setup.md new file mode 100644 index 00000000..6ab8182a --- /dev/null +++ b/doc/getting-started/fish-completion-setup.md @@ -0,0 +1,62 @@ +# Fish Completion Setup + +This page explains how to set up Fish completion for kde-builder. + +## Features + +### Tab Completion +- Complete kde-builder options with TAB +- Complete project and group names +- Complete binaries of projects for `--run` option +- File path completion where required + +### Menu-Complete (Cycling) +Press TAB repeatedly to cycle through options: +```bash +kde-builder --a<TAB><TAB><TAB> +# Cycles: --after → --all-config-projects → --all-kde-projects → --async +``` + +### Mutual Exclusion +Once you use an option, its conflicting options won't be suggested: +```bash +kde-builder --async --<TAB> +# Will NOT show --no-async + +kde-builder --build-only --<TAB> +# Will NOT show --no-build, --install-only, or --src-only +``` + +## Installation and Configuration + +Create symlink to the completion file: + +```bash +# Create the directory if it doesn't exist +mkdir -p ~/.config/fish/completions/ + +# Link to the completion file: the file in .config must end in .fish for Fish to read it. +ln -s ~/.local/share/kde-builder/data/completions/fish/kde-builder.fish ~/.config/fish/completions/kde-builder.fish +``` + +## Reload Configuration + +After making these changes, restart your terminal for the completions to take effect. + +## Optional: System-Wide Installation + +To install for all users (requires root): + +```bash +sudo ln -s ~/.local/share/kde-builder/data/completions/fish/kde-builder.fish /usr/share/fish/vendor_completions.d/kde-builder.fish +``` + +## Uninstallation + +```bash +# Remove user completion file +rm ~/.config/fish/completions/kde-builder.fish + +# Remove global completion file (if installed) +sudo rm /usr/share/fish/vendor_completions.d/kde-builder.fish +``` diff --git a/doc/getting-started/index.md b/doc/getting-started/index.md index cc5497ce..a953e1b2 100644 --- a/doc/getting-started/index.md +++ b/doc/getting-started/index.md @@ -9,6 +9,7 @@ nosearch: before-building alternative-installation bash-completion-setup +fish-completion-setup configure-data building-and-troubleshooting kde-projects-and-selection