Debian Codegraph @

docs/index.md

raw
1 <!--
2 SPDX-FileCopyrightText: Peter Pentchev <[email protected]>
3 SPDX-License-Identifier: BSD-2-Clause
4 -->
5
6 # feature-check - query a program for supported features
7
8 \[[Home][ringlet-feature-check] | [GitLab][gitlab] | [Python API](api/python.md) | [Rust API][rustdoc] | [Download](download.md) | [PyPI][pypi] | [crates.io][crates-io] | [ReadTheDocs][readthedocs]\]
9
10 The `feature-check` tool obtains the list of supported features from
11 a program via various methods (e.g. running it with the `--features`
12 command-line option) and allows other programs to check for the presence
13 and, possibly, versions of specific features.
14
15 [rustdoc]: https://docs.rs/feature-check/latest/
16
17 ## Check for a single feature
18
19 Specify a program name and a feature name; the `feature-check` tool will
20 exit with an exit code of 0 if the program supports it, and a non-zero
21 exit code if the program doesn't support the feature or something goes
22 wrong when querying it (e.g. it doesn't support the `--features` option
23 at all):
24
25 ``` sh
26 #!/bin/sh
27
28 if feature-check confget ini; then
29 # process an INI file with the confget tool
30 fi
31 ```
32
33 If the program needs a different option to display its list of features,
34 specify it using the `feature-check` tool's `-O` option:
35
36 ``` sh
37 [roam@straylight ~]$ feature-check curl AsynchDNS; echo $?
38 2
39 [roam@straylight ~]$ feature-check -O--version curl AsynchDNS; echo $?
40 0
41 [roam@straylight ~]$
42 ```
43
44 To display the version of a feature advertised by the program, use the `-v`
45 option:
46
47 ``` sh
48 [roam@straylight ~]$ feature-check -v timelimit subsecond
49 1.0
50 [roam@straylight ~]$
51 ```
52
53 If the program's features output is on a line which starts with a marker
54 other than "Features: ", specify it using the `-P` option.
55
56 ## Compare a single feature against a version number
57
58 After the program name, specify one or more arguments that, when all
59 concatenated, form a "feature op version" string. The operation may be
60 one of:
61
62 - `lt`, `<`: the program's feature is at an earlier version
63 - `le`, `<=`: the program's feature is at an earlier or the same version
64 - `eq`, `=`: the program's feature is at the specified version
65 - `ge`, `>=`: the program's feature is at a later or the same version
66 - `gt`, `>`: the program's feature is at a later version
67
68 Here are some examples:
69
70 ``` sh
71 [roam@straylight ~]$ feature-check -l feature-check
72 feature-check 0.1.0
73 list 1.0
74 simple 1.0
75 single 1.0
76 [roam@straylight ~]$ feature-check feature-check 'simple <= 1.0' && echo yes
77 yes
78 [roam@straylight ~]$ feature-check feature-check 'simple lt 1.0a' && echo yes
79 yes
80 [roam@straylight ~]$ feature-check feature-check simple gt 1.0a && echo yes
81 [roam@straylight ~]$ feature-check feature-check simple lt 1.0.beta && echo yes
82 [roam@straylight ~]$ feature-check feature-check simple gt 1.0.beta && echo yes
83 yes
84 ```
85
86 ## List a program's features
87
88 Specify the `-l` option and a program name; the `feature-check` tool will
89 query the program's features and display them all. The default output
90 format is one feature per line, name and value separated by a tab.
91 The `-o` option allows specifying alternative output formats; the only one
92 supported so far is `json` which outputs the features as a JSON object.
93
94 ``` sh
95 [roam@straylight ~]$ feature-check -l timelimit
96 subsecond 1.0
97 timelimit 1.9.0
98 [roam@straylight ~]$ feature-check -l -o json timelimit
99 {
100 "subsecond" : "1.0",
101 "timelimit" : "1.9.0"
102 }
103 [roam@straylight ~]$
104 ```
105
106 ## Contact
107
108 The `feature-check` library was written by [Peter Pentchev][roam].
109 It is developed in [a GitLab repository][gitlab]. This documentation is
110 hosted at [Ringlet][ringlet-feature-check] with a copy at [ReadTheDocs][readthedocs].
111
112 [roam]: mailto:[email protected] "Peter Pentchev"
113 [gitlab]: https://gitlab.com/ppentchev/feature-check "The feature-check GitLab repository"
114 [pypi]: https://pypi.org/project/feature-check/ "The feature-check Python Package Index page"
115 [crates-io]: https://crates.io/crates/feature-check "The feature-check crate on crates.io"
116 [readthedocs]: https://feature-check.readthedocs.io/ "The feature-check ReadTheDocs page"
117 [ringlet-feature-check]: https://devel.ringlet.net/misc/feature-check/ "The Ringlet feature-check homepage"