forked from libamtrack/library
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README_DEVELOPERS
586 lines (389 loc) · 25.9 KB
/
README_DEVELOPERS
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
############################################################################################################################
LIBAMTRACK INFORMATION FOR CODE DEVELOPERS --- PLEASE READ CAREFULLY
############################################################################################################################
0. Requirements
1. Basic workflow for compilation of libamtrack from full source - using autotools, list of targets
2. Using the eclipse IDE
3. Doxygen comments
4. Build an R source package tarball
5. Python wrappers
6. Install MinGW toolchain (Windows)
7. Install GSL
8. Make a release (including R package)
9. A note on stopping powers
Contact and feedback
############################################################################################################################
0. Requirements
############################################################################################################################
The GNU Scientific Library (GSL, headers + libraries/binaries) is required for all OSs if you want to compile libamtrack
from source (sections 1 and 8). See section 7 for installation instructions.
To compile the DISTRIBUTED SOURCES of libamtrack: you need the GNU compiler collection gcc and other software(section 1a).
To compile the FULL DEVELOPMENT SOURCES of libamtrack,
make releases/distributions: you need in addition other parts of the GNU toolchain, i.e. the GNU build
system (autotools, i.e. automake, autoconf, and libtool, and m4),
(see sections 1b and 8).
To check out the FULL DEVELOPMENT SOURCE, you also need GIT installed.
You will find required tools depending on your OS here:
Linux
=====
The names might change depending on your distribution. For Ubuntu 14.04 LTS you need:
automake
autoconf
libtool
gcc
gfortran
libgsl0-dev
Plus for development using the Netbeans IDE
openjdk7
netbeans (which is prefereably installed in the user's home directory from the Netbeans homepage)
Using clang instead of gcc
--------------------------
If clang is installed (e.g. at /usr/bin/clang), it can be used as an alternative by exporting:
CC=/usr/bin/clang
CXX=/usr/bin/clang++
before ./configure (see 1a).
Mac OS X
========
XCode and XCode Command Line Tools (we tested with Mac OS X 10.10 Mountain Lion and XCode 6.3.2). Additional autotools
needed can be obtained by an additional package system for Mac OS X (e.g. Homebrew, Fink, MacPorts). On Fink, for example,
use the list / install command to get:
automake(1.15), autoconf, libtool2, pkgconfig
Do not install gcc. Do also not install gfortran if you also want to compile the R package. In this case, use the gfortran
distribution from the "CRAN tools for R compilation on Mac OS X" website (s. below)
Windows
=======
MinGW/MYS
---------
MSYS from MinGW (basic POSIX shell). The MinGW DTK (developer toolkit) if you want to use autotools. The MinGW-based
toolchain for both 32 bit and 64 bit comes with installation of Rtools (http://cran.r-project.org/bin/windows/Rtools/)
that is also needed when compiling R tarball source packages under Windows. Switching between 32 bit and 64 bit
compilation is done by appropriate compiler flags ("-m32" (default) or "-m64"). See section 6 for installation instructions.
Alternatively, you can download the toolchain (http://www.stats.ox.ac.uk/pub/Rtools/multilib/multi.zip) and install
manually independently from Rtools. Also, you can use other configurations of MinGW or the 64bit fork mingw-w64. In this
case you might have to use other procedures or flags (e.g. --host=i686-w64-mingw32 or x86_64-w64-mingw32 for 32/64 bit)
than the ones given in this file. We cannot of course not give any support for those alternatives - but are interested
in your experiences (s.greilich@dkfz.de).
Please make sure - for all Windows installations of MSYS, GSL, R packages, ... - NOT TO USE pathnames with spaces
(i.e. C:\Program Files\MinGW) - that will most likely give you lots of strange errors.
mingw-w64 / MSYS2
-----------------
Alternatively, you can use the mingw-w64 fork of MinGW. From July 2015, all check of libamtrack with Windows will
use this system. It can by installed in parallel with Rtools (s. below).
Install MSYS2 as a POSIX-like console for windows:
- Goto http://msys2.github.io/, download installer for 64bit (e.g. msys2-x86_64-YYYYMMDD.exe)
- Execute installer (not as admin but regular user), install into c:\msys64
- Exit and restart MSYS by calling C:\msys64\mingw64_shell.bat (it is convenient for later use to make a shortcut)
- Do "pacman -Sy" (synchronize local package database with repos)
- Install software needed (gcc, gdb, etc.):
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-gcc-libs
pacman -S mingw-w64-x86_64-gcc-fortran mingw-w64-x86_64-gcc-libgfortran
pacman -S mingw-w64-x86_64-gdb
pacman -S autoconf automake libtool
pacman -S mingw-w64-x86_64-binutils
pacman -S mingw-w64-x86_64-make
pacman -S mingw-w64-x86_64-gsl
pacman -S make
pacman -S bash
- An overview of all tools in the toolchain can be seen by: pacman -S mingw-w64-x86_64-toolchain
- Optionally, you can install the same tools for 32 bit (not required): pacman -S mingw-w64-i686-toolchain
############################################################################################################################
1a. Basic workflow for compilation from distributed source
############################################################################################################################
Download source distribution (e.g. from sourceforge), navigate to download directory and untar by
tar zxvf libamtrack-x.y.tar.gz
Navigate to new directory (cd libamtrack-x.y) and execute
./configure
make
make install
For tweaking (target, installation directory) please see section 1b.
############################################################################################################################
1b. Basic workflow for compilation of libamtrack from full source - using autotools
############################################################################################################################
From revision r1037 on, libamtrack follows the GNU autotool conventions to improve portability and facilitate distribution.
This requires additional files (such as configure.ac, Makefile.am, ChangeLog, NEWS, etc.) and folders (m4) to be placed
in the subversion repository.
In addition, file and folders will be created during the autoconf/automake process (such as aclocal.m4,
config.guess, configure, install.sh, Makefile, etc.). Those files *SHOULD NOT* be committed to the repository.
Please refrain from doing so.
Basic instruction on the use of GNU autotools are found in INSTALL.
The libamtrack sources can be fetched from GIT repository at github.com by:
git clone https://github.com/libamtrack/library.git
In this way you will obtain repository with full history, all previous tags and branches.
To commit changes you did to the code please fork the repository and make a pull request.
As for section 1a, please make sure that GSL_LIB points correctly to your GSL installation (section 7) if you are working
with Windows.
Steps for compilation:
----------------------
i. After you check out libamtrack OR
you updated your local workspace (which could have changed configure.ac) OR
you changed configure.ac yourself run:
mkdir m4
autoreconf --force --install
This will create a configure script plus all necessary other files.
ii. After (i.) OR
you changed a makefile.am OR
you want to switch between RELEASE / DEBUG (or any other) configuration
./configure (for an optimized, 'release' code)
./configure CFLAGS="-O0 -g -DDEBUG" (for a 'debug' version of the code, e.g. to use with gdb)
./configure --enable-shared=no (if you want to produce static libraries, e.g. for portable applications)
If you use eclipse, you can simplify this step by using a separate build configurations.
When using Mac OS X you might consider using multiarchtecture compilation by adding appropriate "-arch" flags (will
create a single library that can be used with multiple architectures)
./configure CC="gcc -arch i386 -arch x86_64" CPP="gcc -E"
which will give 32 AND 64 bit versions on Intel-based Mac, for PowerPC add "-arch ppc" (32 bit) and/or "-arch ppc64"
You can change the default path for installation by "--prefix=/my/installation/path". The flags given in this section
can be used together where applicable.
iii. After (i.) OR
(ii.) OR
any local change in the code:
make all
iv. ### TODO: Describe (and enable)
make check >log.txt 2>&1
make install
make uninstall
make distclean
############################################################################################################################
1c. Non-standard make targets
############################################################################################################################
R-package
===============
Compiles an R package tarball from current libamtrack source. Works also under Windows but will skip test of package (as
multiarchtecture compilation is not (yet) set up correctly). Instead, you should use Rtools and the Windows CMD shell for
testing and building of a binary package after running this target in MSYS2 (see below).
############################################################################################################################
2. Using an IDE
############################################################################################################################
Eclipse 3.6+ supports the autotool toolchain. There are, however, some peculiarities to be considered:
You have to manually set include path:
Right click libamtrack project > Properties > C/C++ general > Path and Symbols
When using a second build configuration with debug flags (see above), eclipse gets confused and you have (TODO: fix)
to prepare debugged code to use with gbd in eclipse using the command line.
Also, Netbeans can be used.
############################################################################################################################
3. Doxygen comments
############################################################################################################################
Doxygen comments are not only used to document libamtrack's C code but they are also used during the scripted generation of
R and Python wrappers. It is essential for them to have it very carefully formatted.
- After @param[??] parameter name should go and then description.
- @param[in] defines an input, @param[out] an return parameter.
- The size of array HAS to be provided in brackets with key word "array of size". It should not be provided in function
declaration in the header file. Both other parameters passed to the function (see example, "n"), numbers and macro
expansions can be used as size, also in mixed or multiple form.
- A whitespace is needed after the first and before last bracket in the function declaration (TODO: Really? When last
variable is an array "[]", the example below fails until the whitespace is removed for the closing bracket).
- In the function declaration there is one parameter per line, with the first parameter in the same line as function name.
- Please refrain from using "/", ";" in the description
Example:
/**
* Returns Z for given elemental symbols
* @param[in] n number of elements in arrays
* @param[in] acronym elemental symbols (array of size n)
* @param[out] Z corresponding Z (array of size n)
* @return status
*/
int AT_Z_from_element_acronym( const long n,
char* acronym[],
long Z[] );
############################################################################################################################
4. Build an R source package tarball
############################################################################################################################
From Jun 2014, development versions of the libamtrack R-packages are provided by R-forge:
http://r-forge.r-project.org/R/?group_id=1918
They are synchronized with the latest libamtrack sources through a night build system (Jenkins).
This workflow is replaced by the make target "R-package" (see section 1), but left here for details on the procedure
behind that target.
The necessary files for producing an R package from libamtrack are found in:
/wrapper/R/R_package package folder structure and input files, script for compilation, hardcoded wrappers
and documentation
/tools/automatic_wrapper_generation R scripts for automatic creation of R/C wrappers
To compile a package, follow first the instructions given in section 1b, then navigate to /wrapper/R/R_package:
Functions that should go to R package are referenced in the text file NAMESPACE. The suffix "_multi" will automatically be
skipped, as R functions are supposed to be able to work on vectors as you should always prefer the "<function_name>_multi"
version of the function over the "<function_name>_single", if possible. If "noR: " is placed in front of the function name
in NAMESPACE a C wrapper will be generated but no corresponding R wrapper. This can be useful if you want to have access
to a function within an R function via ".C" but not a full R function on its own.
Run ./create.package.sh
Use --help to see options
If your function is not in resulting package, use --no-clean option and check output file "collect.doxygen.information.Rout"
for functions that fails (most likely due to faulty doxygen formatting).
The resulting package is an source tarball (libamtrack-version.tar.gz). It can either be distributed by yourself (most likely in
the case of intermediate development versions) or uploaded to CRAN (in case of an official release).
See section 8. How to make a release on how to produce binary packages.
Under Linux and Mac OS, the source package can be simply installed for use in R by typing
(sudo) R CMD INSTALL <package_name>
Under standard Windows, source tarballs cannot be installed with a common R installation. To compile a source package
the best way is to use the RTools (see section 0).
Under Mac OS X, the dedicated gfortran distribution should be used (http://cran.r-project.org/bin/macosx/tools/). Also,
adapt the corresponding lines in the configuration file $R_HOME/etc/makeconf, e.g.:
CC = clang -arch x86_64
CXX = clang++ -arch x86_64
CXXCPP = $(CXX) -arch x86_64 -E
FC = gfortran -arch x86_64
F77 = gfortran -arch x86_64
FLIBS = -L/usr/local/lib/gcc/i686-apple-darwin8/4.2.3 -L/usr/local/lib/gcc/i686-apple-darwin8/4.2.3/x86_64 -lm
OBJC = clang -arch x86_64
OBJCXX = clang++ -arch x86_64
############################################################################################################################
5. Python wrappers
############################################################################################################################
i. make "wrapper/Python/pyamtrack/NAMESPACE" file completely empty this will cause wrappers will be created for (almost)
all functions
ii. run "python generate_Py_wrapper.py" to generate file "pyamtrack.py". The script will complain, but ignore it - some
functions are impossible to translate yet.
iii. copy compiled library to the same directory as "pyamtrack.py": cp ../../../src/.libs/libamtrack.so.0.0.0 libamtrack.so
iv. run "python pyamtrack_example.py" to check sample file.
############################################################################################################################
6. Install Rtools (Windows)
############################################################################################################################
Install the latest version of Rtools from http://cran.r-project.org/bin/windows/Rtools/ with administrator priviledges. This
includes a complete multilib (32/64 bit) toolchain based on MinGW. To our knowledge this is the easiest way, even when you
intend not to compile R source packages but libamtrack only - everything is setup correctly. Since some releases, the
toolchain directory (in "C:\Path\to\Rtools") is named "gcc-x.y.z" instead of usual "MinGW" which might be confusing first.
Make sure Windows environmental variable PATH contains:
C:\Path\to\Rtools\bin + C:\Path\to\Rtools\gcc-x.y.z\bin
This should be autoset by Rtools installer. It is essential that the directory containing the command line tools comes
first or second in the path: there are typically like-named tools46 in other directories, and they will not work.
############################################################################################################################
7. Install GSL
############################################################################################################################
7a. Linux
=========
Most popular distribution offer GSL (libgsl) in their repositories. Please make sure that you install the development version
including headers (e.g. libgsl0-dev).
7b. Mac OS X
============
Please make sure you have XCode and the XCode Command Line Tools installed (tested on Mac OS X 10.8 Mountain Lion, Xcode tools 4.5.2,
gcc version 4.2.1 (Based on Apple Inc. build 5658)).
Download the latest gsl from the GNU homepage, untar (tar zxvf) and navigate into top directory of the sources.
As we want to have both 32 and 64 bit versions (Intel-based Mac) run
./configure CC="gcc -arch i386 -arch x86_64" CPP="gcc -E" --enable-shared=NO
For PowerPC add "-arch ppc" and/or "-arch ppc64", resp. This will create single libraries that can be used with multiple architectures.
Build and check by
make
make check > log.txt 2>&1
then install
sudo make install
gsl is now in /usr/local (or a different place if you have set an individual --prefix flag). ./gsl-config shows that path.
Alternatively, you might want to use a system like FINK or MacPorts to install gsl, but we can not give any details due to missing experience wit that.
We built static libraries, so that libamtrack will be statically link to the gsl routines and not depend on an external dynamic library, making it
package portable, i.e. the user DOES NOT NEED TO HAVE GSL installed!
7c. WINDOWS
===========
i. For regular compilation (as in section 1a, 1b, 8)
----------------------------------------------------
Install the binary package from MSYS2 (see 0)
ii. R package compilation (as for section 4, 8)
-----------------------------------------------
There are subtle differences how regular libamtrack compilation and R package compilation handle GSL and GSL pointers:
Standard Windows compilation only requires a single architecture (e.g. 32 bit if you want to be sure that your programs
run on all, including 64 bit, platforms) that goes (usually) into a standard folder structure (in /usr oder /usr/local):
bin - directory keeping binaries, i.e. executables and dlls
include - include / header files
lib - pre-/static libraries for linking
share - other stuff
R in contrast has developed a solution to deal with multiarchitectures under Windows and thereore assumes a canonical structure of libraries
to deal with multilibs. During R (package) compilation and also executing of R and related subprograms, the make variable R_ARCH_BIN={"i386","x64"}
points to the current architecture, whereever necessary, i.e. using binaries and libraries but not for include:
include - include files (headers), common to all systems
libs/i386 - static libraries for 32 bit
libs/x64 - static libraries for 64 bit
bin/i386 - binaries for 32 bit
bin/x64 - binaries for 64 bit
It will not use "gsl-config" like regular libamtrack compilation. Since R fully supports the use of GSL, the easiest approach is therefore to
download the dedicated pre-build libraries from the Rtools page ("localxxx.zip", http://www.stats.ox.ac.uk/pub/Rtools/R215x.html) and locate
them in a designated location in your MSYS directory (e.g. C:\Path\to\MinGW\msys\1.0\local\Rcompile\local215).
To point to this GSL directory use the make variable
LOCAL_SOFT
*not* GSL_LIB to point to the GSL root directory e.g. "C:/Path/to/MinGW/msys/local/Rcompile/local215" (forward slashes!). LOCAL_SOFT does not
have to be set in the MSYS shell but in both C:\Path\to\R\etc\{i386,{x64}\Makeconf files (thanks to Uwe Ligges for his advice).
Since local215.zip contains static libraries only, the dlls in libamtrack will contain the code of gsl routines and do not depend on an external
dynamic library, making the package portable. I.e. the user DOES NOT NEED TO HAVE GSL installed which is in accordance to R requirements.
Again, to avoid confusion and trouble we recommend to keep two installations of GSL for both purposes (i) and (ii) in two separate locations.
Ideally, you take for (i) the precompiled file from the Rtools page, and compile the library with your toolchain for (ii) for your intended
architecture (32/64 bit) yourself.
############################################################################################################################
8. Make a release (including R package for CRAN)
############################################################################################################################
Release
#######
- Augment "/trunk/ChangeLog", e.g. from svn logs
- Make new folder in /tags, correspoding to version to release, e.g. "0.5.4"
- Adjust "/tags/VERSION/configure.ac": AC_DEFINE(CODE_STATUS, ["Development"], [Status of the code]) --> AC_DEFINE(CODE_STATUS, ["Release"], [Status of the code])
- Adjust "/trunk/configure.ac":
New development number: AC_INIT([libamtrack], [0.5.5], [s.greilich@dkfz.de], [libamtrack])
New development name: AC_DEFINE(CODE_NAME, ["Violet Wombat"], [Cryptonym to faciliate versioning for users])
- Commit changes to SVN (this will be the release's revision number)
These steps can be skipped in case you want to make an intermediate (development) version.
Source distribution
###################
Execute make dist
If release, upload to sourceforge with corresponding folder
Precompiled binaries
####################
For Win (maybe Mac, Linux?): How to make sure that gsl is STATICALLY linked to libamtrack, so users do not have to have GSL?
Linux
-----
Mac OS X
--------
Windows
-------
Binary packages
###############
Linux
-----
RPM / DEB?
Mac OS X
--------
Use PackageMaker (XCode Auxilirary Developer Tools)
Windows
-------
Installer?
R package
#########
Follow instructions given in section 4. Then run tests on tarball:
R CMD check --as-cran libamtrack.VERSION.tar.gz, both as current as alternative user and both with latest stable and development R release (4 tests)
Make sure to switch on "-Wall -pedantic" in ~/.R/Makevars (NOT in the package Makevars) - or similar if you are not using gcc
If successful, upload package tarball to ftp://CRAN.R-project.org/incoming/ using �anonymous� as log-in name and your e-mail address as password (use �ftp�).
Then send mail to CRAN@R-project.org about it with your package name and version in the subject line of the form "CRAN submission �package� �version�"
R package binaries
##################
This process is only needed for intermediate packages and mostly Windows users how do not have their system upgraded to be able to compile tarball
source packages. Release packages will be uploaded to CRAN, the R repository, where Windows and Mac binaries are automatically provided.
Mac and Linux are furthermore able to compile source tarballs.
Linux:
------
Under Linux tarball source packages (package_x.y.z.tar.gz) can be installed directly by
R CMD INSTALL package_x.y.z.tar.gz
so binary packages should not be necessary. But if you use the --build option during this process you will get a binary package, with "--no-inst" R
will not install the package but only produce the binary.
Mac OS X:
---------
Build 32 bit or 64 bit version (skip "--no-inst" to install, too) portable binary
R CMD INSTALL --build --no-inst package_x.y.z.tar.gz
R64 CMD INSTALL --build --no-inst package_x.y.z.tar.gz
or both in a single package
R CMD INSTALL --merge-multiarch --build --no-inst package.tar.gz
This will result in a portable .tgz file.
Windows:
--------
With Rtools installed, start Windows command shell (with administrative priviledges, i.e.
Start button > Search programs and files > Enter "cmd" > Press "Ctrl+Shift+Enter"
Navigate to directory where the package's source tarball (created using ./create.package.sh under Linux) is located.
Now build binary package (NB: Windows environmental variable PATH has to include the R version you are using):
R CMD INSTALL --no-inst --build package_x.y.z.tar.gz
The resulting zip-file can be distributed to all Windows users. They do not need to have gsl installed.
Users can install the binary package within R by
install.packages("C:/PATH/TO/libamtrack_x.y.zip", repos = NULL)
or appropriate menu short-cuts in R GUIs.
If you want to install the package yourself, just skip "--no-inst" during compilation.
############################################################################################################################
9. A note on stopping powers
############################################################################################################################
Stopping power data in libamtrack are primarily for convenient use and not for high-accuracy application. There is no
distinguished between total and electronic stopping power and specific energy per nucleon and per amu!
############################################################################################################################
Contact and feedback
############################################################################################################################
Please send mails considering code development to:
steffen.greilich@dkfz.de or
leszek.grzanka@ifj.edu.pl