-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathreadme.txt
190 lines (149 loc) · 8.7 KB
/
readme.txt
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
*****************************************************************************
Copyright (c) 2006, Colorado School of Mines and others. All rights reserved.
This software and accompanying materials are made available under the terms
of the Common Public License - v1.0, which accompanies this distribution,
and is available at http://www.eclipse.org/legal/cpl-v10.html
*****************************************************************************
The Colorado School of Mines Java Toolkit
-----------------------------------------
The Mines Java Toolkit (JTK) is a set of Java packages and native (non-Java)
software libraries for science and engineering. Applications currently
include digital signal processing, linear algebra, optimization, meshing,
interpolation, and 2D and 3D graphics.
Note: if you modify (or port, or translate, or ...) our source code, then
you have created a "derived work", and should review carefully the terms
of the license that accompanies this software.
Getting the source code
-----------------------
To build and use the Mines JTK, you must first download its source
code from GitHub at https://github.com/dhale/jtk. If you clone this
source code repository using git, then you will be able to easily
update your copy as others make changes. Alternatively, you may use
the Downloads link provided by GitHub to obtain a current snapshot
of the code; but this copy cannot be conveniently updated with git.
If you are using Linux or Mac OS X (10.7+), then you already have
a git command-line client. Various git clients with graphical user
interfaces are also available for Linux, Mac OS X, and Windows,
and git is also available within popular integrated development
environments, such as Eclipse, Netbeans, and IntelliJ IDEA. Note
that git will be necessary if you wish to propose changes (submit
pull requests) for the master branch of the source code repository.
To determine if you have a git command-line client, in a terminal
window type "git". If that command is found, then cd to the
directory that will contain your directory jtk and (2) type the
command
git clone https://github.com/dhale/jtk.git
This command will create a directory jtk in your current working
directory. The subdirectory .git contains a complete copy of the
repository for the Mines Java Toolkit. If instead you simply use
the GitHub Downloads link, then this subdirectory will be absent.
The directory jtk/ has the following subdirectories:
bin/ - platform-dependent scripts (e.g., antrun.sh and javarun.sh)
data/ - data used for demos and testing
doc/ - documentation for tools we use but do not build (e.g., JUnit)
jar/ - JAR files (e.g., junit.jar)
lib/ - platform-specific JNI libraries (e.g., jogl.dll)
src/ - source code files (e.g., main/java/edu/mines/jtk/util/Stopwatch.java)
Tools for building
------------------
To build the Mines JTK, you need these freely available tools:
* Java SE JDK 6.0 (or later):
http://www.oracle.com/technetwork/java/javase/downloads
* Apache Ant 1.7 (or later):
http://ant.apache.org
On Windows, we like to put tools such as the JDK and Ant in a folder named
"C:\pro\". This folder name is shorter than "C:\Program Files" and contains
no spaces, which makes it easy to specify in scripts.
These tools may be used with or without an integrated development
environment (IDE), such as NetBeans, Eclipse, or IntelliJ IDEA.
Building the Mines JTK
----------------------
In your jtk/bin/ directory are scripts for running Ant. Choose an
appropriate script for your platform, and copy it to some directory that is
in your PATH. From any directory, you will want to type the command antrun
and have this script be found. You may of course rename this script to
anything you like. For example, you might rename the script antrun.sh
to be simply "a" (or "a.bat"), which is easier to type.
In your copy of the antrun script, edit the environment variables so that
the script will find your JDK and Ant. (For Linux and Mac OS X systems,
these are in installed in standard locations, so no environment variables
are necessary.)
Then cd to your jtk/ directory (the one that contains build.xml) and type
"antrun" (or whatever you called your ant script). This command should
build the Mines Java Toolkit.
Type "antrun -p" to learn more about other build targets, such as clean
and doc.
Using the Mines JTK
-------------------
After you have built the Mines JTK, you should have the JAR file
jtk/build/jar/edu_mines_jtk.jar.
You may use this file as you would any other JAR file.
To use the Mines JTK, we must launch a Java virtual machine, specifying
all of these JAR files and the locations of our JNI libraries.
In jtk/bin/ are scripts (e.g., javarun.sh) that illustrate how
we do this for different platforms. To use the Mines JTK from the command
line, you should (1) copy the appropriate script to some directory in
your PATH, (2) edit the script to specify the correct directories, and
(3) run a Mines JTK program by typing "javarun name_of_a_java_class".
(Again, you may want to use a shorter name, such as "j" for this script.)
For example, you might run JUnit tests for edu.mines.jtk.util by typing
javarun edu.mines.jtk.util.AllTest
If any of these tests fail, then you may need to edit your javarun script.
These tests depend on only pure Java code; they do not depend on our JNI
libraries. Many of our Java packages contain AllTest suites like this one.
The Mines JTK also comes with demos in jtk/src/demo. There are demos in
multiple languages, but the majority are in Jython. Scripting in Jython
is a powerful and robust way to utilize the Java classes in the Mines JTK,
and is the way that most of us work. We include Jython in a jar file as
well as scripts in the jtk/bin/ directory, so that these demos can be run
without any additional installations.
To execute the Jython demos you should (1) copy the appropriate script
(jythonrun.sh or jythonrun.bat) to some directory in your PATH, (2) edit
the script to specify the correct directories, and (3) run a Jython
program by typing "jythonrun program_name.py". (You may want to use a
shorter name, such as "jy" for this script.)
3D graphics in the Mines JTK
-----------------------------
Our packages for 3D graphics are built on JOGL, a Java binding for the
OpenGL API. JAR files for JOGL on 64-bit operating systems are provided
with the Mines JTK. To test 3D graphics on Linux or Mac OS X, type
javarun.sh edu.mines.jtk.ogl.HelloTest
You should see a white square, painted via OpenGL. This program also
prints the OpenGL vendor and version number. That number should not
be less than 1.2.
If instead you see a "java.lang.UnsatisfiedLinkError", then perhaps
the JOGL JAR files required for your operating system are not provided
with the Mines JTK. You can check the JOGL web site for appropriate
JAR files. Put them with the other platform-specific JAR files in
the directory jtk/jar/.
Development using the Mines JTK
-------------------------------
The layout of directories and files for the Mines JTK was designed to
conform to that expected by common development tools and IDEs. However,
before using these more advanced tools, we recommend that you first
build and use the JTK with only Ant and the JDK, as described above.
(By not providing pre-built JAR files, we gently force you to do so.)
When developing your own software, you should not use package names
that begin with "edu.mines.jtk", unless you are making modifications
or additions to the Mines JTK that you wish to contribute back to us.
The prefix edu.mines.jtk makes our class names unique.
Therefore, most classes that you write will have a different prefix,
and your build process will create a JAR file different from our
edu_mines_jtk.jar. To do this easily, you may copy and modify our
directory layout and the file build.xml to create your own JAR file.
By adding that JAR file to the CLASSPATH list in your javarun script,
you can easily use your Java packages with those in the Mines JTK.
In fact, this is what most of us do. We have our own private projects
in which we implement new ideas with Java packages, which may or may
not be someday included in the Mines JTK. (For convenience, the prefix
for the package names in our private projects may be much shorter than
"edu.mines.jtk".) Only those Java packages that are both well written
and useful to others are eventually moved to edu.mines.jtk.
Development using Scala
-----------------------
Scala is a relatively new programming language that supports both
object-oriented and functional programming and the use of existing
Java packages. The Mines JTK does not currently require Scala.
However, if you define the environment variable SCALA_HOME, the
Ant build script build.xml will compile any Scala source files
and include Scala classes in the JAR file edu_mines_jtk.jar.