projects / mirror_ovs.git / blame
| Commit | Line | Data |
|---|---|---|
| 4c5a4181 SF |
1 | .. |
| 2 | Licensed under the Apache License, Version 2.0 (the "License"); you may | |
| 3 | not use this file except in compliance with the License. You may obtain | |
| 4 | a copy of the License at | |
| 5 | ||
| 6 | http://www.apache.org/licenses/LICENSE-2.0 | |
| 7 | ||
| 8 | Unless required by applicable law or agreed to in writing, software | |
| 9 | distributed under the License is distributed on an "AS IS" BASIS, WITHOUT | |
| 10 | WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the | |
| 11 | License for the specific language governing permissions and limitations | |
| 12 | under the License. | |
| 13 | ||
| 14 | Convention for heading levels in Open vSwitch documentation: | |
| 15 | ||
| 16 | ======= Heading 0 (reserved for the title in a document) | |
| 17 | ------- Heading 1 | |
| 18 | ~~~~~~~ Heading 2 | |
| 19 | +++++++ Heading 3 | |
| 20 | ''''''' Heading 4 | |
| 21 | ||
| 22 | Avoid deeper levels because they do not render well. | |
| 23 | ||
| 24 | ==================================== | |
| 25 | Bash command-line completion scripts | |
| 26 | ==================================== | |
| 27 | ||
| 28 | There are two completion scripts available, ovs-appctl-bashcomp.bash and | |
| 29 | ovs-vsctl-bashcomp.bash respectively. | |
| 30 | ||
| 31 | ovs-appctl-bashcomp | |
| 32 | ------------------- | |
| 33 | ||
| 34 | ovs-appctl-bashcomp.bash adds bash command-line completion support for | |
| 35 | ovs-appctl, ovs-dpctl, ovs-ofctl and ovsdb-tool commands. | |
| 36 | ||
| 37 | Features | |
| 38 | ~~~~~~~~ | |
| 39 | ||
| 40 | - Display available completion or complete on unfinished user input (long | |
| 41 | option, subcommand, and argument). | |
| 42 | ||
| 43 | - Subcommand hints | |
| 44 | ||
| 45 | - Convert between keywords like ``bridge``, ``port``, ``interface``, or ``dp`` | |
| 46 | and the available record in ovsdb. | |
| 47 | ||
| 48 | Limitations | |
| 49 | ~~~~~~~~~~~ | |
| 50 | ||
| 51 | - Only supports a small set of important keywords (``dp``, ``datapath``, ``bridge``, ``switch``, | |
| 52 | ``port``, ``interface``, ``iface``). | |
| 53 | ||
| 54 | - Does not support parsing of nested options. For example: | |
| 55 | ||
| 56 | ||
| 57 | :: | |
| 58 | ||
| 59 | $ ovsdb-tool create [db [schema]] | |
| 60 | ||
| 61 | - Does not support expansion on repeated argument. For example: | |
| 62 | ||
| 63 | :: | |
| 64 | ||
| 65 | $ ovs-dpctl show [dp...]). | |
| 66 | ||
| 67 | - Only supports matching on long options, and only in the format ``--option | |
| 68 | [arg]``. Do not use ``--option=[arg]``. | |
| 69 | ||
| 70 | ovs-vsctl-bashcomp | |
| 71 | ------------------- | |
| 72 | ||
| 73 | ovs-vsctl-bashcomp.bash adds bash command-line completion support for ovs-vsctl | |
| 74 | command. | |
| 75 | ||
| 76 | Features | |
| 77 | ~~~~~~~~ | |
| 78 | ||
| 79 | - Display available completion and complete on user input for global/local | |
| 80 | options, command, and argument. | |
| 81 | ||
| 82 | - Query database and expand keywords like ``table``, ``record``, ``column``, or | |
| 83 | ``key``, to available completions. | |
| 84 | ||
| 85 | - Deal with argument relations like 'one and more', 'zero or one'. | |
| 86 | ||
| 87 | - Complete multiple ovs-vsctl commands cascaded via ``--``. | |
| 88 | ||
| 89 | Limitations | |
| 90 | ~~~~~~~~~~~ | |
| 91 | ||
| 92 | Completion of very long ``ovs-vsctl`` commands can take up to several seconds. | |
| 93 | ||
| 94 | Usage | |
| 95 | ----- | |
| 96 | ||
| 97 | The bashcomp scripts should be placed at ``/etc/bash_completion.d/`` to be | |
| 98 | available for all bash sessions. Running ``make install`` will place the | |
| 99 | scripts to ``$(sysconfdir)/bash_completion.d/``, thus, the user should specify | |
| 100 | ``--sysconfdir=/etc`` at configuration. If OVS is installed from packages, the | |
| 101 | scripts will automatically be placed inside ``/etc/bash_completion.d/``. | |
| 102 | ||
| 103 | If you just want to run the scripts in one bash, you can remove them from | |
| 104 | ``/etc/bash_completion.d/`` and run the scripts via ``. | |
| 105 | ovs-appctl-bashcomp.bash`` or ``. ovs-vsctl-bashcomp.bash``. | |
| 106 | ||
| 107 | Tests | |
| 108 | ----- | |
| 109 | ||
| 110 | Unit tests are added in ``tests/completion.at`` and integrated into autotest | |
| 111 | framework. To run the tests, just run ``make check``. |