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
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
|
====== Torch Installation Manual ======
{{anchor:install.dok}}
Currently Torch7 installation can be done only from the
sources. Binary releaseses will be distributed soon.
====== Installing from sources ======
{{anchor:install.sources}}
''Torch7'' is mainly made out of ''ANSI C'' and ''Lua'', which makes
it easy to compile everywhere. The graphical interface is based on QT
and requires a ''C++'' compiler.
The installation process became easily portable on most platforms,
thanks to [[http://www.cmake.org|CMake]], a tool which replace the
aging ''configure/automake'' tools. CMake allows us to detect and
configure Torch properly.
You will find here step-by-step instructions for each system we are supporting.
You are also strongly encouraged to read the [[#CMakeHints|CMake hints]]
section for more details on CMake (and before reporting a problem).
If you are a programmer, you might want to produce your own
[[#DevPackages|development package]].
===== Linux =====
{{anchor:install.linux}}
==== A. Requirements ====
Torch compilation requires a number of standard packages described below:
* **Mandatory:**
* A ''C/C++'' compiler. [[http://clang.llvm.org|CLang]] is great. The [[http://gcc.gnu.org|GNU compiler]] or Intel compiler work fine.
* [[http://www.cmake.org|CMake]] version 2.6 or later is required.
* [[http://gnuplot.info|Gnuplot]], version ''4.4'' or later is recommended for best experience.
* **Recommended:**
* [[http://tiswww.case.edu/php/chet/readline/rltop.html|GNU Readline]]
* [[http://git-scm.com/|Git]] to keep up-to-date sources
* [[http://trolltech.com/products|QT 4.4]] or newer development libraries
* BLAS. [[https://github.com/xianyi/OpenBLAS|OpenBLAS]] is recommended for that purpose on Intel computers.
* LAPACK. [[https://github.com/xianyi/OpenBLAS|OpenBLAS]] is recommended for that purpose on Intel computers.
The installation of most of these packages should be rather
straightforward. For ''Ubuntu 10.04 LTS'' system we use the
''apt-get'' magic:
For GCC:
<file>
sudo apt-get install gcc g++
</file>
If you prefer to use CLang:
<file>
sudo apt-get install clang
</file>
CMake reads CC and CXX variables. If you do not want to use the default compiler, just do
<file>
export CC=clang
export CXX=clang++
</file>
To install the additional packages, do:
<file>
sudo apt-get install cmake
sudo apt-get install libreadline5-dev
sudo apt-get install git-core
sudo apt-get install gnuplot
</file>
Please adapt according to your distribution.
Note: readline library is helpful for better command line interaction,
but it is not required. It is only used when QT is installed.
We require ''QT 4.4'' for handling graphics (//beware// not installing QT 4.3
or older). If it is not found at compile time, Torch will still compile but
no graphics will be available. On ''Ubuntu 10.04 LTS'' distribution you can
install it with
<file>
sudo apt-get install libqt4-core libqt4-gui libqt4-dev
</file>
An excellent BLAS/LAPACK implementation is also recommended for speed. See
our [[blas|BLAS recommendations]].
==== B. Getting Torch sources ====
{{anchor:install.sources}}
Torch7 is being developed on [[http://github.com|github]].
<file>
git clone git://github.com/andresy/torch.git
</file>
==== C. Configuring Torch ====
{{anchor:install.config}}
We use ''CMake'' for configuring ''Torch''. We //highly// recommend to create
first a dedicated build directory. This eases cleaning up built objects,
but also allow you to build Torch with //various configurations//
(e.g. Release and Debug in two different build directories).
<file>
cd torch
mkdir build
cd build
cmake ..
</file>
The ''..'' given to ''cmake'' indicates the directory where the
sources are. We chose here to have a ''build'' directory inside
''torch'', but it could be anywhere else. In that latter case, go
instead in your build directory and then do:
<file>
cmake /path/to/torch/sources
</file>
CMake detects external libraries or tools necessary for Torch, and
produces Makefiles such that Torch is then easily compilable on your
platform. If you prefer the GUI version of CMake, you can replace
''cmake'' by ''ccmake'' in the above command lines. In particular, it
is //strongly encouraged// to use ''ccmake'' for finer configuration
of Torch.
The most common Torch configuration step you might want to perform is
changing the installation path. By default, Torch will be installed in
''/usr/local''. You will need super-user rights to perform that. If
you are not root on your computer, you can instead specifying a
install directory to ''CMake'' on the above ''cmake'' command:
<file>
cmake .. -DCMAKE_INSTALL_PREFIX=/my/install/path
</file>
Equivalently you can set the variable ''CMAKE_INSTALL_PREFIX'' if you
use ''ccmake'' GUI. Please, see [[http://www.cmake.org|CMake
documentation]] or //at least// [[#CMakeHints|some of our CMake
hints]] for more details on configuration.
==== D. Compiling and installing ====
{{anchor:install.compile}}
If the configuration was successful, Makefiles should have appeared in
your build directory. Compile Torch with:
then compile and install with:
<file>
make install
</file>
This last command might possibly be prefixed by ''sudo'' if you are
installing Torch in ''/usr/local''.
==== E. Running Torch ====
{{anchor:install.run}}
Now Torch should be installed in ''/usr/local'' or in
''/my/install/path'' if you chose to use the ''CMAKE_INSTALL_PREFIX''
when configuring with CMake. Lua executables (''torch-lua'',
''torch-qlua'' and ''torch'') are found in the ''bin'' sub-directory of
these installation directories.
<file>
/usr/local/bin/torch-lua
Lua 5.1.4 Copyright (C) 1994-2008 Lua.org, PUC-Rio
> require 'torch'
> = torch.Tensor(5):zero()
0
0
0
0
0
[torch.Tensor of dimension 5]
>
</file>
For convenience, you might want to add to your ''PATH'' the path to
lua binaries. The executable ''torch-lua'' is a simple Lua interpreter
(as provided on [[http://www.lua.org|Lua website]]), while ''torch-qlua''
has enhanced interactivity (like completion) and is able to handle
graphics and QT widgets.
For best experience we suggest using the ''torch'' executable, which
preloads the most commonly used libraries into the global namespace.
<file>
/usr/local/bin/torch
Try the IDE: torch -ide
Type help() for more info
Torch 7.0 Copyright (C) 2001-2011 Idiap, NEC Labs, NYU
Lua 5.1 Copyright (C) 1994-2008 Lua.org, PUC-Rio
torch> =torch.randn(10,10)
1.3862 1.5983 -2.0216 -0.1502 1.9467 -1.2322 0.1628 -2.6253 1.3255 -0.5784
0.1363 -1.2638 -1.0661 0.0233 1.3064 -0.8817 1.1424 1.0952 -0.2147 0.7712
1.1348 -0.8596 -0.6102 0.9137 -1.1582 -0.3301 0.5250 1.3631 -0.4051 -0.9549
-0.2734 -0.0914 0.9728 1.3272 -0.4126 -0.1264 -1.2936 -0.2120 1.3040 -1.9991
-0.9642 0.2367 -0.5246 -0.0476 -0.6586 1.8705 0.8482 -1.2768 -0.0782 0.5403
0.4551 -1.4549 -0.7079 -1.6308 -0.2086 -1.7208 -1.4915 0.9703 0.3661 0.5051
0.3082 0.3188 -1.1247 0.1343 -0.2671 -0.4596 -0.2618 1.7482 0.4714 0.5217
-0.8406 -0.2372 -0.1504 0.6982 -0.5437 0.7447 0.0229 -2.4998 0.7367 -1.2721
-0.3993 1.5155 -0.3685 -0.0534 -0.0495 -0.1002 -0.3652 0.1248 -0.2693 0.9159
-1.5035 0.7326 -0.6262 0.2715 0.0543 -0.7419 -0.6758 -0.0221 0.5342 -0.4262
[torch.DoubleTensor of dimension 10x10]
torch>
</file>
You can get more help about ''torch'':
<file>
/usr/local/bin/torch -h
Torch7 Shell
Usage: torch [options] [script [args]]
General options:
-b|-bare start a bare environment (no libs preloaded)
-e string execute string
-l lib require lib
-i enter interactive mode after executing script [false]
-v|-version show version information [false]
-h|-help this help [false]
Qt options:
-nographics|-ng disable all the graphical capabilities [false]
-ide enable IDE (graphical console) [false]
-onethread run lua in the main thread (might be safer) [false]
</file>
===== MacOS X =====
==== A. Requirements ====
Torch compilation requires a number of standard packages described below:
* **Mandatory:**
* A ''C/C++'' compiler. [[http://clang.llvm.org|CLang]] is great. The [[http://gcc.gnu.org|GNU compiler]] or Intel compiler work fine.
* [[http://www.cmake.org|CMake]] version 2.6 or later is required.
* [[http://gnuplot.info|Gnuplot]], version ''4.4'' or later is recommended for best experience.
* **Recommended:**
* [[http://tiswww.case.edu/php/chet/readline/rltop.html|GNU Readline]]
* [[http://git-scm.com/|Git]] to keep up-to-date sources
* [[http://trolltech.com/products|QT 4.4]] or newer development libraries
* BLAS. [[https://github.com/xianyi/OpenBLAS|OpenBLAS]] is recommended for that purpose on Intel computers.
* LAPACK. [[https://github.com/xianyi/OpenBLAS|OpenBLAS]] is recommended for that purpose on Intel computers.
Installation of gcc should be done by installing the
[[http://developer.apple.com/tools/xcode|the Apple developer
tools]]. These tools should also be available on you MacOS X
installation DVD.
CMake can be retrieved from
[[http://www.cmake.org/HTML/Download.html|CMake website]] (you can
take the **DMG** installer). However, we found it was as simple to use
[[http://mxcl.github.com/homebrew/|Homebrew]], or [[http://www.macports.org/|MacPorts]]
which are necessary anyway for git and the Readline library. We recommend to avoid
[[http://finkproject.org/|Fink]], which tends to be always
outdated. Assuming you installed Homebrew, just do:
<file>
brew install readline
brew install cmake
brew install git
brew install gnuplot
</file>
For installing QT, one can use Homebrew, but it might take too long to
compile. Instead, you can
[[http://trolltech.com/downloads/opensource/appdev/mac-os-cpp|download]]
the binary **DMG** file available on [[http://trolltech.com|Trolltech
website]] and install it.
An excellent BLAS/LAPACK implementation is also recommended for speed. See
our [[blas|BLAS recommendations]].
Last but not least, GCC >= 4.6 is *required* to enable OpenMP on MacOS X. This
is a bit crazy, but compiling against OpenMP with previous versions of GCC
will give you random segfaults and trap errors (a known issue on the web).
We strongly recommend you to install GCC 4.6, to fully benefit from Torch's
fast numeric routines. A very simple way of doing so is to install the
[[http://gcc.gnu.org/wiki/GFortranBinaries|GFortran]] libraries, which are
packaged as a simple dmg, ready to install. That'll automatically install gcc
and g++. Once this is done, set your CC and CXX before building Torch:
<file>
export CC=/usr/local/gfortran/bin/gcc
export CXX=/usr/local/gfortran/bin/g++
</file>
==== B. Getting Torch sources ====
Same as [[#install.sources|getting sources]] for linux.
==== C. Configuring Torch ====
Same as [[#install.config|configuring]] for linux.
==== D. Compiling and Installing ====
Same as [[#install.compile|compiling]] for linux.
==== E. Running Torch ====
Same as [[#install.run|runnning]] for linux.
===== FreeBSD =====
{{anchor:install.freebsd}}
==== A. Requirements ====
Torch compilation requires a number of standard packages described below:
* **Mandatory:**
* A ''C/C++'' compiler. [[http://clang.llvm.org|CLang]] is great. The [[http://gcc.gnu.org|GNU compiler]] or Intel compiler work fine.
* [[http://www.cmake.org|CMake]] version 2.6 or later is required.
* [[http://gnuplot.info|Gnuplot]], version ''4.4'' or later is recommended for best experience.
* **Recommended:**
* [[http://tiswww.case.edu/php/chet/readline/rltop.html|GNU Readline]]
* [[http://git-scm.com/|Git]] to keep up-to-date sources
* [[http://trolltech.com/products|QT 4.4]] or newer development libraries
* BLAS. [[https://github.com/xianyi/OpenBLAS|OpenBLAS]] is recommended for that purpose on Intel computers.
* LAPACK. [[https://github.com/xianyi/OpenBLAS|OpenBLAS]] is recommended for that purpose on Intel computers.
GCC and CLang come with FreeBSD install. However, only GCC 4.2 is installed by default (for licensing reasons).
We prefer to use CLang. If you want to stick with GCC, we recommend installing GCC 4.4 or GCC 4.6 instead of using
GCC 4.2 (poor performance on recent CPUs).
<file>
pkg_add -r gcc46
</file>
CMake reads CC and CXX variables. If you do not want to use the default compiler, just do
<file>
export CC=clang
export CXX=clang++
</file>
Additional packages can be easily installed with:
<file>
pkg_add -r readline
pkg_add -r cmake
pkg_add -r git
pkg_add -r gnuplot
</file>
Note: on FreeBSD 9.0, it seems ''pdflib'' (a dependency of gnuplot) is not available as binary. Please,
install gnuplot instead in the port tree:
<file>
cd /usr/ports/math/gnuplot
make install clean
</file>
For installing QT, use also ''pkg_add -r qt4'', followed by ''pkg_add -r qt4-XXX'', where
XXX is one of the components (or tools) listed on [[http://www.freebsd.org/doc/en/books/porters-handbook/using-qt.html|Qt FreeBSD page]].
Be sure to install all components and tools listed there.
An excellent BLAS/LAPACK implementation is also recommended for speed. See
our [[blas|BLAS recommendations]].
==== B. Getting Torch sources ====
Same as [[#install.sources|getting sources]] for linux.
==== C. Configuring Torch ====
Same as [[#install.config|configuring]] for linux. Note that dynamic RPATH (related to ''$ORIGIN'') do not work properly
on my FreeBSD 9. You can deactivate this with the ''WITH_DYNAMIC_RPATH'' option.
<file>
cmake .. -DCMAKE_INSTALL_PREFIX=/my/install/path -DWITH_DYNAMIC_RPATH=OFF
</file>
==== D. Compiling and Installing ====
Same as [[#install.compile|compiling]] for linux.
==== E. Running Torch ====
Same as [[#install.run|runnning]] for linux.
===== Cygwin =====
//We do not recommend// Cygwin installation. Cygwin is pretty slow, and we
could not manage to make QT 4.4 work under Cygwin. Instead prefer
[[#Windows|native windows]] installation.
===== Windows =====
{{anchor:Windows}}
//** Torch7 is not yet Windows compatible, coming soon **//
===== CMake hints =====
{{anchor:CMakeHints}}
CMake is well documented on [[http://www.cmake.org|http://www.cmake.org]].
====CMake and CLang====
If you like to use [[http://clang.llvm.org|CLang]] for compiling Torch7, assuming a proper
CLang installation, you only have to do
<file>
export CC=clang
export CXX=clang++
</file>
before calling cmake command line.
====CMake GUI====
Under Windows, CMake comes by default with a GUI. Under Unix system it is
quite handy to use the //text GUI// available through ''ccmake''.
''ccmake'' works in the same way than ''cmake'': go in your build directory and
<file>
ccmake /path/to/torch/source
</file>
Windows and Unix GUI works in the same way: you ''configure'', //possibly several times//,
until CMake has detected everything and proposes to ''generate'' the configuration.
After each configuration step, you can modify CMake variables to suit your needs.
====CMake variables====
CMake is highly configurable thanks to //variables// you can set when
executing it. It is really easy to change these variables with CMake GUI. If you want
to stick with the command line you can also change a variable by doing:
<file>
cmake /path/to/torch/source -DMY_VARIABLE=MY_VALUE
</file>
where ''MY_VARIABLE'' is the name of the variable you want to set and
''MY_VALUE'' is its corresponding value.
===Interesting standard CMake variables===
* ''CMAKE_INSTALL_PREFIX'': directory where Torch is going to be installed
* ''CMAKE_BUILD_TYPE'': ''Release'' for optimized compilation, ''Debug'' for debug compilation.
* ''CMAKE_C_FLAGS'': add here the flags you want to pass to the C compiler (like ''-Wall'' for e.g.)
=== Notable Torch7 CMake variables ===
* ''WITH_BLAS'': specify which BLAS you want to use (if you have several on your computers). Can be mkl/open/goto/acml/atlas/accelerate/veclib/generic.
* ''WITH_LUA_JIT'': say to CMake to compile Torch7 against LuaJIT instead of Lua. (default is OFF)
* ''WITH_QTLUA'': compile QtLua if Qt is found (default is ON)
* ''WITH_QTLUA_IDE'': compile QtLua IDE if Qt is found (default is ON)
* ''WITH_RPATH'': use RPATH such that you do not need to add Torch7 install library path in LD_LIBRARY_PATH. (default is ON)
* ''WITH_DYNAMIC_RPATH'': if used together with WITH_RPATH, will make library paths relative to the Torch7 executable. If you move the install directory, things will still work. This flag does not work on FreeBSD. (default is ON).
====CMake caches everything====
As soon as CMake performed a test to detect an external library, it saves
the result of this test in a cache and will not test it again.
If you forgot to install a library (like QT or Readline), and install it
after having performed a CMake configuration, it will not be used by Torch
when compiling.
//In doubt//, if you changed, updated, added some libraries that should be used by Torch, you should
//erase your build directory and perform CMake configuration again//.
===== Development Torch packages =====
{{anchor:DevPackages}}
If you want to develop your own package, you can put it in the ''dev''
sub-directory. Packages in ''dev'' are all compiled in the same way that the
ones in ''packages'' sub-directory. We prefer to have this directory to make a
clear difference between official packages and development packages.
Alternatively, you can use [[#PackageManager|Torch package manager]]
to build and distribute your packages.
===== The Torch Package Management System =====
{{anchor:PackageManager}}
Torch7 has a built-in package management system that makes it very easy
for anyone to get extra (experimental) packages, and create and distribute
yours.
Calling ''torch-pkg'' without arguments will give you some help:
<file>
/usr/local/bin/torch-pkg
Torch7 Package Manager
Usage: torch-pkg [options] <command> [argument]
Supported Commands:
help print this help
install install a package (download + build + deploy)
download download a package locally
build build a local package
deploy deploy a package (build it if necessary)
list list available packages
search search for a package
add add a server address to local config ($HOME/.torchpkg/config)
Arguments for install|download:
<pkg-name> a package name (to be found in one of the configured repos)
<pkg-repo> the full address of a GIT repository
<pkg-url> the URL of a simple package (should be a tar/tgz/tbz)
Arguments for add:
<base-url> a base URL where GIT repos or tars can be found
Options:
-v|-verbose be more verbose
-l|-local local install
-n|-nodeps do not install dependencies (when installing)
-d|-dry dry run
</file>
It's fairly self-explanatory. You can easily get a list of the available
packages:
<file>
/usr/local/bin/torch-pkg list
--> retrieving package lists from servers
--> parallel
A parallel computing framework for Torch7, with serialization facilities
hosted at: https://github.com/clementfarabet/lua---parallel
--> image
An image-processing toolbox for Torch7
hosted at: https://github.com/clementfarabet/lua---image
--> optim
An optimization toolbox for Torch7
hosted at: https://github.com/koraykv/optim
...
</file>
To install a new package, simply do:
<file>
/usr/local/bin/torch-pkg install pkgname
</file>
The sources of the packages are downloaded and kept in a hidden
directory in your home:
<file>
torch-pkg install image
ls ~/.torch/torch-pkg/image/
</file>
If you just want to get the sources of a package, without
installing it, you can get it like this:
<file>
/usr/local/bin/torch-pkg download pkgname
</file>
And then build it and install it:
<file>
cd pkgname
/usr/local/bin/torch-pkg build
/usr/local/bin/torch-pkg deploy
</file>
If you need to distribute your own packages, you just have
to create a package file, which contains one entry per package,
and then make it available online. Users can then easily add
that file to their repository by doing:
<file>
/usr/local/bin/torch-pkg add http://url/to/config
</file>
The config typically looks like:
<file>
pkg = pkg or {}
pkg.image = {
git = 'https://github.com/clementfarabet/lua---image',
description = 'An image-processing toolbox for Torch7',
dependencies = {'sys', 'xlua'},
commit = 'master'
}
pkg.optim = {
git = 'https://github.com/koraykv/optim',
description = 'An optimization toolbox for Torch7',
dependencies = {},
commit = 'newpack'
}
pkg.parallel = {
git = 'https://github.com/clementfarabet/lua---parallel',
description = 'A parallel computing framework for Torch7, with serialization facilities',
dependencies = {'sys'},
commit = 'newpack'
}
</file>
====== Installing from binaries ======
{{anchor:install.binary}}
** This section is not applicable now as we have not produced binaries yet. **
** Please [[#install.sources|install from sources]]. **
|