toolkit/devtools/gcli/source/docs/index.md@6474c204b198 (annotated)
toolkit/devtools/gcli/source/docs/index.md
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
| michael@0 | 1 | |
| michael@0 | 2 | # About GCLI |
| michael@0 | 3 | |
| michael@0 | 4 | ## GCLI is a Graphical Command Line Interpreter. |
| michael@0 | 5 | |
| michael@0 | 6 | GCLI is a command line for modern computers. When command lines were invented, |
| michael@0 | 7 | computers were resource-limited, disconnected systems with slow multi-tasking |
| michael@0 | 8 | and poor displays. The design of the Unix CLI made sense in 1970, but over 40 |
| michael@0 | 9 | years on, considering the pace of change, there are many improvements we can |
| michael@0 | 10 | make. |
| michael@0 | 11 | |
| michael@0 | 12 | CLIs generally suffer from poor discoverability; It's hard when faced with a |
| michael@0 | 13 | blank command line to work out what to do. As a result the majority of programs |
| michael@0 | 14 | today use purely graphical user interfaces, however in doing so, they lose some |
| michael@0 | 15 | of the benefits of CLIs. CLIs are still used because generally, in the hands of |
| michael@0 | 16 | a skilled user they are faster, and have a wider range of available options. |
| michael@0 | 17 | |
| michael@0 | 18 | GCLI attempts to get the best of the GUI world and the CLI world to produce |
| michael@0 | 19 | something that is both easy to use and learn as well as fast and powerful. |
| michael@0 | 20 | |
| michael@0 | 21 | GCLI has a type system to help ensure that users are inputting valid commands |
| michael@0 | 22 | and to enable us to provide sensible context sensitive help. GCLI provides |
| michael@0 | 23 | integration with JavaScript rather than being an alternative (like CoffeeScript). |
| michael@0 | 24 | |
| michael@0 | 25 | |
| michael@0 | 26 | ## History |
| michael@0 | 27 | |
| michael@0 | 28 | GCLI was born as part of the |
| michael@0 | 29 | [Bespin](http://ajaxian.com/archives/canvas-for-a-text-editor) project and was |
| michael@0 | 30 | [discussed at the time](http://j.mp/bespin-cli). The command line component |
| michael@0 | 31 | survived the rename of Bepsin to Skywriter and the merger with Ace, got a name |
| michael@0 | 32 | of it's own (Cockpit) which didn't last long before the project was named GCLI. |
| michael@0 | 33 | It is now being used in the Firefox's web console where it doesn't have a |
| michael@0 | 34 | separate identity but it's still called GCLI outside of Firefox. It is also |
| michael@0 | 35 | used in [Eclipse Orion](http://www.eclipse.org/orion/). |
| michael@0 | 36 | |
| michael@0 | 37 | |
| michael@0 | 38 | ## Environments |
| michael@0 | 39 | |
| michael@0 | 40 | GCLI is designed to work in a number of environments: |
| michael@0 | 41 | |
| michael@0 | 42 | 1. As a component of Firefox developer tools. |
| michael@0 | 43 | 2. As an adjunct to Orion/Ace and other online editors. |
| michael@0 | 44 | 3. As a plugin to any web-page wishing to provide its own set of commands. |
| michael@0 | 45 | 4. As part of a standalone web browser extension with it's own set of commands. |
| michael@0 | 46 | |
| michael@0 | 47 | |
| michael@0 | 48 | ## Related Pages |
| michael@0 | 49 | |
| michael@0 | 50 | Other sources of GCLI documentation: |
| michael@0 | 51 | |
| michael@0 | 52 | - [Writing Commands](writing-commands.md) |
| michael@0 | 53 | - [Writing Types](writing-types.md) |
| michael@0 | 54 | - [Developing GCLI](developing-gcli.md) |
| michael@0 | 55 | - [Writing Tests](writing-tests.md) / [Running Tests](running-tests.md) |
| michael@0 | 56 | - [The Design of GCLI](design.md) |
| michael@0 | 57 | - Source |
| michael@0 | 58 | - The most up-to-date source is in [this Github repository](https://github.com/joewalker/gcli/). |
| michael@0 | 59 | - When a feature is 'done' it's merged into the [Mozilla clone](https://github.com/mozilla/gcli/). |
| michael@0 | 60 | - From which it flows into [Mozilla Central](https://hg.mozilla.org/mozilla-central/file/tip/browser/devtools/commandline). |
| michael@0 | 61 | - [Demo of GCLI](http://mozilla.github.com/gcli/) with an arbitrary set of demo |
| michael@0 | 62 | commands |
| michael@0 | 63 | - Other Documentation |
| michael@0 | 64 | - [Embedding docs](https://github.com/mozilla/gcli/blob/master/docs/index.md) |
| michael@0 | 65 | - [Status page](http://mozilla.github.com/devtools/2011/status.html#gcli) |
| michael@0 | 66 | |
| michael@0 | 67 | |
| michael@0 | 68 | ## Accessibility |
| michael@0 | 69 | |
| michael@0 | 70 | GCLI uses ARIA roles to guide a screen-reader as to the important sections to |
| michael@0 | 71 | voice. We welcome [feedback on how these roles are implemented](https://bugzilla.mozilla.org/enter_bug.cgi?product=Firefox&component=Developer+Tools:+Graphic+Commandline+and+Toolbar&rep_platform=All&op_sys=All&short_desc=GCLI). |
| michael@0 | 72 | |
| michael@0 | 73 | The command line uses TAB as a method of completing current input, this |
| michael@0 | 74 | prevents use of TAB for keyboard navigation. Instead of using TAB to move to |
| michael@0 | 75 | the next field you can use F6. In addition to F6, ALT+TAB, CTRL+TAB, META+TAB |
| michael@0 | 76 | make an attempt to move the focus on. How well this works depends on your |
| michael@0 | 77 | OS/browser combination. |
| michael@0 | 78 | |
| michael@0 | 79 | |
| michael@0 | 80 | ## Embedding GCLI |
| michael@0 | 81 | |
| michael@0 | 82 | There are 3 basic steps in using GCLI in your system. |
| michael@0 | 83 | |
| michael@0 | 84 | 1. Import a GCLI JavaScript file. |
| michael@0 | 85 | For serious use of GCLI you are likely to be creating a custom build (see |
| michael@0 | 86 | below) however if you just want to have a quick play, you can use |
| michael@0 | 87 | ``gcli-uncompressed.js`` from [the gh-pages branch of GCLI] |
| michael@0 | 88 | (https://github.com/mozilla/gcli/tree/gh-pages) |
| michael@0 | 89 | Just place the following wherever you place your script files. |
| michael@0 | 90 | |
| michael@0 | 91 | <script src="path/to/gcli-uncompressed.js" type="text/javascript"></script> |
| michael@0 | 92 | |
| michael@0 | 93 | 2. Having imported GCLI, we need to tell it where to display. The simplest |
| michael@0 | 94 | method is to include an elements with the id of ``gcli-input`` and |
| michael@0 | 95 | ``gcli-display``. |
| michael@0 | 96 | |
| michael@0 | 97 | <input id="gcli-input" type="text"/> |
| michael@0 | 98 | <div id="gcli-display"></div> |
| michael@0 | 99 | |
| michael@0 | 100 | 3. Tell GCLI what commands to make available. See the sections on Writing |
| michael@0 | 101 | Commands, Writing Types and Writing Fields for more information. |
| michael@0 | 102 | |
| michael@0 | 103 | GCLI uses the CommonJS AMD format for it's files, so a 'require' statement |
| michael@0 | 104 | is needed to get started. |
| michael@0 | 105 | |
| michael@0 | 106 | require([ 'gcli/index' ], function(gcli) { |
| michael@0 | 107 | gcli.addCommand(...); // Register custom commands |
| michael@0 | 108 | gcli.createTerminal(); // Create a user interface |
| michael@0 | 109 | }); |
| michael@0 | 110 | |
| michael@0 | 111 | The createTerminal() function takes an ``options`` objects which allows |
| michael@0 | 112 | customization. At the current time the documentation of these object is left |
| michael@0 | 113 | to the source. |
| michael@0 | 114 | |
| michael@0 | 115 | |
| michael@0 | 116 | ## Backwards Compatibility |
| michael@0 | 117 | |
| michael@0 | 118 | The goals of the GCLI project are: |
| michael@0 | 119 | |
| michael@0 | 120 | - Aim for very good backwards compatibility with code required from an |
| michael@0 | 121 | 'index' module. This means we will not break code without a cycle of |
| michael@0 | 122 | deprecation warnings. |
| michael@0 | 123 | |
| michael@0 | 124 | There are currently 3 'index' modules: |
| michael@0 | 125 | - gcli/index (all you need to get started with GCLI) |
| michael@0 | 126 | - demo/index (a number of demo commands) |
| michael@0 | 127 | - gclitest/index (GCLI test suite) |
| michael@0 | 128 | |
| michael@0 | 129 | Code from these modules uses the module pattern to prevent access to internal |
| michael@0 | 130 | functions, so in essence, if you can get to it from an index module, you |
| michael@0 | 131 | should be ok. |
| michael@0 | 132 | |
| michael@0 | 133 | - We try to avoid needless change to other modules, however we don't make any |
| michael@0 | 134 | promises, and don't provide a deprecation cycle. |
| michael@0 | 135 | |
| michael@0 | 136 | Code from other modules uses classes rather than modules, so member variables |
| michael@0 | 137 | are exposed. Many classes mark private members using the `_underscorePrefix` |
| michael@0 | 138 | pattern. Particular care should be taken if access is needed to a private |
| michael@0 | 139 | member. |
| michael@0 | 140 | |
| michael@0 | 141 | |
| michael@0 | 142 | ## Creating Custom Builds |
| michael@0 | 143 | |
| michael@0 | 144 | GCLI uses [DryIce](https://github.com/mozilla/dryice) to create custom builds. |
| michael@0 | 145 | If dryice is installed (``npm install .``) then you can create a built |
| michael@0 | 146 | version of GCLI simply using ``node gcli.js standard``. DryIce supplies a custom |
| michael@0 | 147 | module loader to replace RequireJS for built applications. |
| michael@0 | 148 | |
| michael@0 | 149 | The build will be output to the ``built`` directory. The directory will be |
| michael@0 | 150 | created if it doesn't exist. |
