/
interactive.html
251 lines (174 loc) · 10.5 KB
/
interactive.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en-us">
<head>
<title>Interactive mode - </title>
<link href='http://fonts.googleapis.com/css?family=Copse' rel='stylesheet' type='text/css'>
<link href='/resources/site.css' rel='stylesheet' type='text/css'>
<link href='/resources/syntax.css' rel='stylesheet' type='text/css'>
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js">
</script>
</head>
<body>
<!-- Topbar
================================================== -->
<div class="cf" id="more" >
<div id="top">
<div class="container">
<a class="brand" href="/">SBT</a>
<ul class="nav">
<li><a href="/learn.html">Learn</a>
<li><a href="/download.html">Download</a>
<li><a href="/community.html">Community</a></li>
<li><a href="#top">Top</a></li>
</ul>
</div>
</div>
</div>
<div class="cf" id="container">
<div class="span2 columns container-spacer"><p> </p></div>
<div id="intro" class="span10 columns content">
<div id="head" class="cf">
<div id="name" class="left">
<h1>sbt</h1>
<h2>Interactive mode</h2>
</div>
</div>
<div id="features" class="cf"><div id="feature-list">
<ul class="left">
<li id="feature"><h4><a href="#basic_completion">How to use tab completion</a></h4></li>
<li id="feature"><h4><a href="#verbose_completion">How to show more tab completion suggestions</a></h4></li>
<li id="feature"><h4><a href="#show_keybindings">How to view basic JLine keybindings</a></h4></li>
<li id="feature"><h4><a href="#change_keybindings">How to modify the default JLine keybindings</a></h4></li>
<li id="feature"><h4><a href="#prompt">How to configure the prompt string</a></h4></li>
<li id="feature"><h4><a href="#history">How to use history</a></h4></li>
<li id="feature"><h4><a href="#history_file">How to change the location of the interactive history file</a></h4></li>
<li id="feature"><h4><a href="#share_history">How to share interactive history across projects</a></h4></li>
<li id="feature"><h4><a href="#disable_history">How to disable interactive history</a></h4></li>
<li id="feature"><h4><a href="#pre_commands">How to start interactive mode after executing some commands first</a></h4></li>
</ul>
</div></div>
<div id="pagecontent" class="cf">
<p>By default, sbt's interactive mode is started when no commands are provided on the command line or when the <code>shell</code> command is invoked.</p>
<h4 id="basic_completion">Using tab completion</h4>
<p>As the name suggests, tab completion is invoked by hitting the tab key.
Suggestions are provided that can complete the text entered to the left of the current cursor position.
Any part of the suggestion that is unambiguous is automatically appended to the current text.
Commands typically support tab completion for most of their syntax.</p>
<p>As an example, entering <code>tes</code> and hitting tab:</p>
<pre><code>> tes<TAB>
</code></pre>
<p>results in sbt appending a <code>t</code>:</p>
<pre><code>> test
</code></pre>
<p>To get further completions, hit tab again:</p>
<pre><code>> test<TAB>
test-frameworks test-listeners test-loader test-only test-options test:
</code></pre>
<p>Now, there is more than one possibility for the next character, so sbt prints the available options.
We will select <code>test-only</code> and get more suggestions by entering the rest of the command and hitting tab twice:</p>
<pre><code>> test-only<TAB><TAB>
-- sbt.DagSpecification sbt.EmptyRelationTest sbt.KeyTest sbt.RelationTest sbt.SettingsTest
</code></pre>
<p>The first tab inserts an unambiguous space and the second suggests names of tests to run.
The suggestion of <code>--</code> is for the separator between test names and options provided to the test framework.
The other suggestions are names of test classes for one of sbt's modules.
Test name suggestions require tests to be compiled first.
If tests have been added, renamed, or removed since the last test compilation, the completions will be out of date until another successful compile.</p>
<h4 id="verbose_completion">Showing more completions</h4>
<p>Some commands have different levels of completion. Hitting tab multiple times increases the verbosity of completions. (Presently, this feature is rarely used.)</p>
<h4 id="show_keybindings">Showing JLine keybindings</h4>
<p>Both the Scala and sbt command prompts use JLine for interaction. The Scala REPL contains a <code>:keybindings</code> command to show many of the keybindings used for JLine. For sbt, this can be used by running one of the <code>console</code> commands (<code>console</code>, <code>console-quick</code>, or <code>console-project</code>) and then running <code>:keybindings</code>. For example:</p>
<pre><code>> console-project
[info] Starting scala interpreter...
...
scala> :keybindings
Reading jline properties for default key bindings.
Accuracy not guaranteed: treat this as a guideline only.
1 CTRL-A: move to the beginning of the line
2 CTRL-B: move to the previous character
...
</code></pre>
<h4 id="change_keybindings">Changing JLine keybindings</h4>
<p>JLine, used by both Scala and sbt, uses a configuration file for many of its keybindings.
The location of this file can be changed with the system property <code>jline.keybindings</code>.
The default keybindings file is included in the sbt launcher and may be used as a starting point for customization.</p>
<h4 id="prompt">Configure the prompt string</h4>
<p>By default, sbt only displays <code>></code> to prompt for a command.
This can be changed through the <code>shellPrompt</code> setting, which has type <code>State => String</code>.
<a href="https://github.com/harrah/xsbt/wiki/Build-State">State</a> contains all state for sbt and thus provides access to all build information for use in the prompt string.</p>
<p>Examples:
Liquid error: No such file or directory - posix_spawnp</p>
<h4 id="history">Using history</h4>
<p>Interactive mode remembers history, even if you exit sbt and restart it.
The simplest way to access history is with the up arrow key. The following
commands are also supported:</p>
<ul>
<li><code>!</code> Show history command help.</li>
<li><code>!!</code> Execute the previous command again.</li>
<li><code>!:</code> Show all previous commands.</li>
<li><code>!:n</code> Show the last n commands.</li>
<li><code>!n</code> Execute the command with index <code>n</code>, as shown by the <code>!:</code> command.</li>
<li><code>!-n</code> Execute the nth command before this one.</li>
<li><code>!string</code> Execute the most recent command starting with 'string'</li>
<li><code>!?string</code> Execute the most recent command containing 'string'</li>
</ul>
<h4 id="history_file">Changing the history file location</h4>
<p>By default, interactive history is stored in the <code>target/</code> directory for the current project (but is not removed by a <code>clean</code>).
History is thus separate for each subproject.
The location can be changed with the <code>historyPath</code> setting, which has type <code>Option[File]</code>.
For example, history can be stored in the root directory for the project instead of the output directory:</p>
<p>Liquid error: No such file or directory - posix_spawnp</p>
<p>The history path needs to be set for each project, since sbt will use the value of <code>historyPath</code> for the current project (as selected by the <code>project</code> command).</p>
<h4 id="share_history">Use the same history for all projects</h4>
<p>The previous section describes how to configure the location of the history file.
This setting can be used to share the interactive history among all projects in a build instead of using a different history for each project.
The way this is done is to set <code>historyPath</code> to be the same file, such as a file in the root project's <code>target/</code> directory:</p>
<p>Liquid error: No such file or directory - posix_spawnp</p>
<p>The <code>in LocalRootProject</code> part means to get the output directory for the root project for the build.</p>
<h4 id="disable_history">Disable interactive history</h4>
<p>If, for whatever reason, you want to disable history, set <code>historyPath</code> to <code>None</code> in each project it should be disabled in:</p>
<p>Liquid error: No such file or directory - posix_spawnp</p>
<h4 id="pre_commands">Run commands before entering interactive mode</h4>
<p>Interactive mode is implemented by the <code>shell</code> command.
By default, the <code>shell</code> command is run if no commands are provided to sbt on the command line.
To run commands before entering interactive mode, specify them on the command line followed by <code>shell</code>.
For example,</p>
<pre><code>$ sbt clean compile shell
</code></pre>
<p>This runs <code>clean</code> and then <code>compile</code> before entering the interactive prompt.
If either <code>clean</code> or <code>compile</code> fails, sbt will exit without going to the prompt.
To enter the prompt whether or not these initial commands succeed, prepend <code>-shell</code>, which means to run <code>shell</code> if any command fails.
For example,</p>
<pre><code>$ sbt -shell clean compile shell
</code></pre>
</div>
</div>
</div>
</div>
<script type="text/javascript" src="/jquery.scrollto.min.js"></script>
<script type="text/javascript">
(function($){ $(function(){
$("#top").click(function(){ $("#intro").ScrollTo(); })
var applyH = function() {
$("#intro, .feature").each(function (i, elt) {
if ($(elt).height() < $(window).height()) {
$(elt).height($(window).height());
}
});
};
$(window).bind('resize', function() { applyH(); });
applyH();
$('#features a, .st').click(function(e){
var h = $(this).attr('href');
if(h && h[0] && h[0] == '#') {
e.preventDefault();
$(h).ScrollTo({
callback:function(){ window.location.hash = h;}
});
}
});
});})(jQuery);
</script>
</body>
</html>