/
get-started.html
447 lines (409 loc) · 18.1 KB
/
get-started.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
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Kraftwagen | Get started</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Kraftwagen is a set of Drupal Tools for a everything in code and install profile / drush make based workflow.">
<meta name="author" content="Rolf van de Krol">
<link href="/css/bootstrap.css" rel="stylesheet">
<link href="/css/bootstrap-responsive.css" rel="stylesheet">
<link href="/css/font-awesome.css" rel="stylesheet">
<link href="/css/kraftwagen.css" rel="stylesheet">
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link rel="apple-touch-icon-precomposed" sizes="144x144" href="/img/apple-touch-icon-144x144.png">
<link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/apple-touch-icon-114x114.png">
<link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/apple-touch-icon-72x72.png">
<link rel="apple-touch-icon-precomposed" href="/img/apple-touch-icon-57x57.png">
<link rel="shortcut icon" href="/img/favicon.ico">
</head>
<body data-spy="scroll" data-target=".kw-sidebar">
<header class="get-started">
<div class="container">
<h1>Get your Kraftwagen started!</h1>
</div>
</header>
<div class="container">
<div class="row">
<div class="span4 kw-sidebar">
<div class="kw-sidebar-inner">
<div class="logo"><a href="/"><img src="img/logo-small.png" /></a></div>
<ul class="nav nav-list kw-sidenav">
<li><a href="#installation"><i class="icon-download-alt"></i> Get Kraftwagen</a></li>
<li><a href="#new-project"><i class="icon-plus-sign"></i> New project</a></li>
<li><a href="#setup-project"><i class="icon-bolt"></i> Existing project</a></li>
<li><a href="#build"><i class="icon-magic"></i> Building</a></li>
<li><a href="#initialize"><i class="icon-road"></i> Initialize database</a></li>
<li><a href="#update"><i class="icon-refresh"></i> Update project</a></li>
<li><a href="#conclusion"><i class="icon-ok"></i> Conclusion</a></li>
</ul>
</div>
</div>
<div class="span8">
<p>
This tutorial is aimed at software developers that are familiar with
Drupal and not afraid of a little command line.
</p>
<section id="installation">
<div class="page-header">
<h2>Get Kraftwagen</h2>
</div>
<p>
First make sure to have
<a href="https://github.com/drush-ops/drush">Drush</a> installed. Versions 5.x and 6.x are supported.
Kraftwagen builds its command line interface on Drush.
</p>
<p>
Go to the directory where Drush expects extensions — on
Unix/OSX this is usually <code>~/.drush/</code> — and clone
the Kraftwagen Drush extension from GitHub. After this you should
clear the drush command cache.
</p>
<pre data-language="shell">cd ~/.drush
git clone "git://github.com/kraftwagen/kraftwagen.git"
drush cc drush
</pre>
<p>
You can keep your Kraftwagen up-to-date by doing a
<code>git pull</code> from its directory.
</p>
<h3>Per project</h3>
<p>
We maintain a <a href="https://github.com/kraftwagen/tools">tool
to install Drush and Kraftwagen local to your project</a>. Apart
from this link we consider it beyond the scope of this tutorial.
</p>
</section>
<section id="new-project">
<div class="page-header">
<h2>Create a new project</h2>
</div>
<pre data-language="shell">
cd ~
mkdir example_project
cd example_project
drush kw-np # or `drush kw-new-project`
</pre>
<p>
The <code>kw-new-project</code> command will ask some questions
— a the project name (both human and machine) and the
location of a <em>skeleton repository</em> — after which it
will clone the <em>skeleton repository</em> to generate your
project files in <code>~/example_project/src/</code>.
</p>
<p>
We maintain a
<a href="https://github.com/kraftwagen/skeleton">basic skeleton
repository</a> on GitHub from which you can use (simply fork to
create your own <em>skeletons</em>). Take a look at the
<a href="https://github.com/kraftwagen/skeleton/tree/panopoly">panopoly</a>
branch in our example skeleton to a great example how your own
opinionated skeleton could look. You can use this Panopoly
skeleton by specifying
<code>git://github.com/kraftwagen/skeleton.git</code> as the
repository URL and <code>panopoly</code> as the branch to use.
</p>
<p>
Now the source of the project is created in <code>src/</code>.
This is the directory that you would usually want under version
control. After this you can skip to the procedure of running the
<a href="#setup-project-sub">setup</a>.
</p>
<p>
The source of a Kraftwagen project is a
<a href="http://drupal.org/developing/distributions">Drupal
install profile</a>. Both Drupal core and contributed modules are
pulled in using Drush’ own <code>make</code> command and some
<code>*.make</code> files. This way <em>your</em> repository only
contains <strong>your</strong> code.
</p>
</section>
<section id="setup-project">
<div class="page-header">
<h2>Get an existing project running</h2>
</div>
<p>
If you have an existing Kraftwagen project under version control
you simply create a directory for that project, change to it, and
clone/checkout the source code into <code>src/</code>.
</p>
<pre data-language="shell">
cd ~
mkdir example_project
cd example_project
git clone $REPO_URL src
</pre>
<h3 id="setup-project-sub">Run setup</h3>
<p>
<pre data-language="shell">
cd ~/example_project
drush kw-s # or `drush kw-setup`
</pre>
This creates the <code>builds/</code> directory, which will
contain all the builds, and the <code>cnf/</code> directory with
the following files and directories in it:
</p>
<dl>
<dt><code>settings.php</code> and <code>settings.local.php</code></dt>
<dd>
The settings files are copied from the <code>src/cnf/</code>
directory. These files contain target-specific settings for your
Drupal installation. Later, when building an actual Drupal
installation, these files are symlinked into it.
</dd>
<dt><code>environment</code></dt>
<dd>
This file by default contains one word <code>production</code>,
it is used to determine which environment we currently run in.
</dd>
<dt><code>files/</code></dt>
<dd>
The <code>files/</code> directory is used to store user uploads.
At this point it is empty. Later, when building an actual Drupal
installation, it is symlinked into it.
</dd>
</dl>
<p>
You should change the <code>settings.local.php</code> file to be
able to connect to the database. Furthermore, if you want to use
the development settings, change the contents of the
<code>enviroment</code> file to <code>development</code>.
</p>
</section>
<section id="build">
<div class="page-header">
<h2>Building</h2>
</div>
<p>
The source of the project is not a working Drupal installation. It
doesn’t even contain Drupal itself. It needs to be <em>build</em>.
</p>
<pre data-language="shell">
cd ~/example_project
drush kw-b # or `drush kw-build`
</pre>
<p>
A build creates a <code>*.make</code> file out of your
<code>src/tools/build.make.tpl</code> ready for consumption by
<code>drush make</code> (which is run as part of <code>kw-build</code>).
This will copy the content of your
<code>src/</code> directory into <code>profiles/$NAME/</code>,
where <code>$NAME</code> is the project key specified in
<code>build.make.tpl</code>.
</p>
<p>
When <code>drush make</code> has finished Kraftwagen will <em>symlink</em>
your settings files and <code>files/</code> directory from
<code>cnf/</code> into the <code>sites/default/</code> directory of
the new build.
</p>
<p>
Finally Kraftwagen creates of updates a <em>symlink</em> from the
directory in <code>builds/</code> where your new build resides
(identified by a timestamp), to <code>build/</code>.
</p>
</section>
<section id="initialize">
<div class="page-header">
<h2>Initialize the database</h2>
</div>
<pre data-language="shell">
cd ~/example_project/build
drush kw-id # or `drush kw-initialize-database`
</pre>
<p>
This basically runs <code>drush site-install $PROFILE_NAME</code>.
Where Kraftwagen sets <code>$PROFILE_NAME</code> to the basename
of the <code>*.info</code> file in the root of <code>src/</code>.
</p>
</section>
<section id="update">
<div class="page-header">
<h2>Update your Kraftwagen project</h2>
</div>
<p>
When your code has changed, it is very likely that your database
needs to be synchronized to reflect the new code.
</p>
<p>
Until now, Kraftwagen hasn’t done much more for you than copying
some files around and creating some symlinks. All Kraftwagen
commands we executed do just that or provide simple convenience
wrappers around existing Drush commands. The updating process is
a bit different.
</p>
<pre data-language="shell">
cd ~/example_project/build
drush kw-u # or `drush kw-update`
</pre>
<p>
This basically runs four sub-commands:
<ol>
<li>Apply module dependencies</li>
<li>Run <code>hook_update_N</code> implementations</li>
<li>Revert all Features</li>
<li>Run manifests</li>
</ol>
Below we explain each of these sub-commands (they can be run
individually as well).
</p>
<h3>Apply module dependencies</h3>
<p>
Drupal has an excellent way of defining the dependencies of
modules. Yet we missed a method to automatically enable all
dependencies of an <em>install profile</em> and uninstall all modules that
are not required, in a running site (Drupal only takes care of
this during installation).
</p>
<p>
To execute this sub-command by itself:
</p>
<pre data-language="shell">
cd ~/example_project/build
drush kw-amd development # or `drush kw-apply-module-dependencies development`
</pre>
<p>
An important difference between <code>drush kw-amd</code>
and Drupal’s installation process is the support for
<em>environment dependencies</em>. As you can see
in the code above, we pass the <code>development</code> environment.
This instructs <code>drush kw-amd</code> to enable
dependencies for the <code>development</code> environment.
In <code>*.info</code> files this is specified with:
</p>
<pre>
env_dependencies[development][] = devel
</pre>
<h3>Running <code>hook_update_N</code> implementations</h3>
<p>
Drupal defines database migrations in <code>hook_update_N</code>
functions, which can be run with:
</p>
<pre data-language="shell">
cd ~/example_project/build
drush updatedb
</pre>
<p>
Kraftwagen provides <a href="https://github.com/kraftwagen/kw-manifests">manifests</a>,
a versatile which also allows you to write your database migrations.
It is recommended to use <code>hook_update_N</code> implementations
only for schema migrations, and otherwise use Kraftwagen’s manifests.
</p>
<h3>Reverting Features</h3>
<p>
Here we simply use the Drush command that Features exposes
to synchronize the database with the defined components.
</p>
<pre data-language="shell">
cd ~/example_project/build
drush features-revert-all
</pre>
<h3>Run manifests</h3>
<p>
Kraftwagen’s manifests are named (database) migrations that are
defined in modules and can be used to synchronize anything that
cannot be done with <code>hook_update_N</code> (schema changes)
or Features (e.g.: node types, fields, variables, CTools exportables).
Manifests are mainly used to create nodes (or other entities) and
assign dynamic variables. Manifests need to be
<a href="http://en.wikipedia.org/wiki/Idempotence">idempotent</a>,
which means they can safely be executed multiple times.
</p>
<p>
Manifests are registered in a module’s <code>*.install</code> file
using <code>hook_kw_manifests_info()</code>. For example:
</p>
<pre data-language="php">
/**
* Implements hook_kw_manifests_info().
*/
function mymodule_kw_manifests_info() {
return array('my_manifest' => array(
'callback' => 'mymodule_manifest_define_homepage',
));
}
function mymodule_manifest_define_homepage() {
kw_itemnames_ensure(
'node',
'homepage',
array(
'title' => 'Welcome!',
),
array(
'type' => 'page',
'language' => LANGUAGE_NONE,
'body' => array(
LANGUAGE_NONE => array(array(
'value' => '<p>Welcome to my site!</p>',
'format' => 'filtered_html',
))
)
)
);
}
</pre>
<p>
In this example we use the
<a href="https://github.com/kraftwagen/kw-itemnames">kw-itemnames</a>
module to ensure a certain node is existing.
</p>
<p>
To be able to use this example, you should add both <code>kw_manifest</code>
and <code>kw_itemnames_entity</code> to the dependencies of your module and
run <code>drush kw-amd development</code> after that.
</p>
<p>
In the <a href="https://github.com/kraftwagen/kw-manifests/blob/master/kw_manifests.api.php">API
documentation</a> of Kraftwagen Manifests the
other options are explained. It is for
example possible to define that a manifest depends on another
manifest and/or limit a manifest to an environment.
</p>
<p>
The <a href="https://github.com/kraftwagen/kw-manifests">kw-manifests</a>
module registers a Drush command to run all
manifests. Just like <code>drush kw-amd</code> it accepts the
environment as an argument.
</p>
<pre data-language="shell">
cd ~/example_project/build
drush kw-m development # or `drush kw-manifests development`
</pre>
</section>
<section id="conclusion">
<div class="page-header">
<h2>Conclusion</h2>
</div>
<p>
Enjoy the ride with Kraftwagen… Any questions or remarks: find us on
<a href="https://github.com/kraftwagen">GitHub</a>!
</p>
</section>
<footer>
<hr />
<p>
Spread the news: <span class="st_twitter"></span><span class="st_facebook" ></span><span class="st_googleplus"></span><span class="st_linkedin"></span>
</p>
<p>
Development of Kraftwagen is sponsored by <a href="http://hoppinger.com/" class="hoppinger"><img src="img/hoppinger.png" alt="Hoppinger" /></a>
</p>
<p>
This work is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/deed.en_US">Creative Commons Attribution-ShareAlike 3.0 Unported License</a>
</p>
</footer>
</div>
</div>
</div>
<script src="http://code.jquery.com/jquery-latest.js"></script>
<script src="/js/bootstrap.js"></script>
<script src="/js/rainbow.js"></script>
<script src="/js/app.js"></script>
<script type="text/javascript">var _gaq = [['_setAccount', 'UA-36687951-1'], ['_trackPageview']];</script>
<script type="text/javascript" src="http://www.google-analytics.com/ga.js"></script>
<script type="text/javascript" src="http://w.sharethis.com/button/buttons.js"></script>
<script type="text/javascript">stLight.options({publisher: "23d62cc2-75a8-4f7a-8bc0-ef6411540241", doNotCopy: true});</script>
</body>
</html>