-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME-2-configure
231 lines (164 loc) · 9.18 KB
/
README-2-configure
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
The APL interpreter can be configured by means of ./configure options (see
also file INSTALL in this directory). In addition to the standard options
provided by ./configure (that are described in file INSTALL),
the following GNU APL specific ./configure options are recognized:
--with-android
This option prevents the instantiation of CIN, COUT, and CERR. This may
be needed when GNU APL is compiled for Android, since Android applications
are using a different I/O model than standard C++ programs.
--with-libapl
This option builds GNU APL as a shared library (libapl.so) rather than an
executable. This option is often combined with option --with-android even
though the library is not built for Android, but because the executable
that is linked with libapl.so) has its own I/O channels.
--with-sqlite3=[ARG]
Build the native function for SQL using sqlite3. ARG may provide a
non-default location of the sqlite3 library.
--with-postgresql=[ARG]
Build the native function for SQL using PostgreSQL. ARG may provide a
non-default location of the postgresql library.
ASSERT_LEVEL_WANTED=n
There are numerous Assert() and Assert1 macros in the source code of the
APL interpreter. These macros check more (Assert1) or less (Assert)
obvious assumptions that throw exceptions if they turn out to be wrong.
Like for dynamic logging, these macros have negative performance impacts
and they can be disabled.
By default, ASSERT_LEVEL_WANTED=1 and that disables the Assert1() macro
and enables the Assert() macro
ASSERT_LEVEL_WANTED=2 enables both macros.
ASSERT_LEVEL_WANTED=0 disables both macros; this gives the maximum
performance, but at the same time bears the risk that internal errors
of the APL interpreter are not detected. Example:
./configure ASSERT_LEVEL_WANTED=2
APSERVER_TRANSPORT
APSERVER_PORT
APSERVER_PATH
APserver is a program that is needed to support shared variables. APserver
is started automatically and has a communication channel to every APL
interpreter instance and to every AP started (manually or automatically
by an APL interpreter instance). The communication channel can be TCP,
abstract Unix domain sockets, or normal Unix domain sockets.
1. TCP communication is the default communication channel that is also
use when APSERVER_TRANSPORT is not ./configured. APserver listens on
port number 16366 by default; this can be changed via APSERVER_PORT
like this:
./configure APSERVER_TRANSPORT=TCP APSERVER_PORT=40000
2. Abstract Unix domain sockets are a GNU/linux specific variant that allows
allows for sockets without a corresponding file in the file system.
APserver listens on socket named "/tmp/GNU-APL/APserver" by default;
the name can be changed with APSERVER_PATH like this:
./configure APSERVER_TRANSPORT=LINUX APSERVER_PATH=my-APserver-path
3. Normal Unix domain sockets are a GNU/linux specific variant that requires
a file in the file system to work. The permissions of that file control
which programs can connect to APserver (BUT MAY ALSO PREVENT APserver
FROM OPERATING PROPERLY!). Due to the many different possibilities for
the ownership and permissions for the file, GNU APL does not create the
file but leaves that to the user. By default APserver listens on the
socket named "/tmp/GNU-APL/APserver" (and a file with that name
should exist before APL is started); the name can be changed with
APSERVER_PATH like this:
./configure APSERVER_TRANSPORT=UNIX APSERVER_PATH=my-APserver-path
CORE_COUNT_WANTED
This experimental option specifies the number of CPU cores to be used.
The value is a number, 'all', 'argv', or 'syl'. The interpreter has
sequential code and parallel code which is selected as follows:
value code
0 sequential (default, one core is used)
1 parallel one core is used
N parallel N > 0 cores are used
all -1 parallel all existing cores are being used,
argv -2 parallel the number of cores can be set by command line option
-cc N (same as all if -cc is not given).
syl -3 parallel the number of cores can be changed in APL via ⎕SYL,
initially 1.
Example:
./configure CORE_COUNT_WANTED=4
CIN_COLOR_WANTED
CERR_COLOR_WANTED
COUT_COLOR_WANTED
RESET_COLORS_WANTED
CLEAR_EOL_WANTED
These options were used in GNU APL 1.0 to configure output coloring.
Output coloring can now specified in GNU APL's preference file. This
is more flexible than configuring the colors at compile time.
DYNAMIC_LOG_WANTED=yes
The APL interpreter has more than 30 log categories. Each log category can
be turned on or off in order to troubleshoot the APL interpreter. There are
two ways to control the logging categories: statically or dynamically.
Statically means that it is decided at compile time if a log category
shall be on or off. Dynamically means that a log category can be turned
on and off at run-time (with the command ]LOG).
Dynamic logging has a performance penalty since every potential log
printout has an if () statement that checks if the log category is turned
on or off. With static logging this if () statement has a constant value
that will be optimized away by the C++ compiler. Dynamic logging also
slightly increases the size of the APL interpreter.
In both cases (static or dynamic logging), the file src/Logging.def defines
the logging categories at start-up of the APL interpreter. If the first
argument of the log_def() macro is 0 then the log category is initially
disabled (and remains disabled if static logging is used); if it is 1
then the log category is initially enabled. Example:
./configure DYNAMIC_LOG_WANTED=yes
MAX_RANK_WANTED=n
Set the maximum rank of APL values to n. The default value is 8. Ranks
smaller than 4 should be avoided. There is no performance penalty for
increasing the max. rank, but every additional dimension takes 4-8 bytes
of memory for every APL value (even those with a smaller rank), Example:
./configure MAX_RANK_WANTED=10
PRINT_SEMA_WANTED=yes
This option is now obsolete.
VALUE_CHECK_WANTED=yes
There is a function called check_value() that checks every new APL value
for completeness. This check helps finding faults in the interpreter, but
decreases the performance of the interpreter. Example:
./configure VALUE_CHECK_WANTED=yes
VALUE_HISTORY_WANTED=yes
There is a macro called ADD_EVENT that records the history of APL values.
This history helps finding faults in the interpreter, but
decreases the performance of the interpreter. Example:
./configure VALUE_HISTORY_WANTED=yes
PERFORMANCE_COUNTERS_WANTED=yes
GNU APL has some build-in counters for performace measurements. These counters
are normally disabled, but can be enabled via this option. Example:
./configure PERFORMANCE_COUNTERS_WANTED=yes
VF_TRACING_WANTED=yes
You can enable tracing of changes to value flags. This creates a lot of
debug output and consequently has considerable performance impacts. Example:
./configure VF_TRACING_WANTED=yes
SHORT_VALUE_LENGTH_WANTED=12
The interpreter distinguishes long values and short APL values. Short values
are allocated with a single call to "new" that allocates the Shape of the
value and its ravel. Long values allocate the value header with one call to
"new" and then the ravel with another call to "new". Long values are
therefore a little slower than short values. By increasing
SHORT_VALUE_LENGTH_WANTED you get fewer new calls (and consequently better
performance) at the cost of more memory. Example:
./configure SHORT_VALUE_LENGTH_WANTED=42
GPROF_WANTED=yes
Setting GPROF_WANTED adds -pg flags to CXXFLAGS and LDFLAGS and that
enables support for gprof profiling of the apl interpreter. Example:
./configure GPROF_WANTED=yes
VISIBLE_MARKERS_WANTED=yes
GNU APL uses a handful of Unicode characters as internal pad characters
when formatting output. Normally these pad characters are in a private
Unicode range in order to minimize the chance that they are output on
purpose. Unfortunately that makes debugging of the output formatting
difficult. With VISIBLE_MARKERS_WANTED=yes, characters ⁰, ¹, ... are used
as internal pad (and these characters will display as spaces when displayed.
./configure VISIBLE_MARKERS_WANTED=yes
-------------------------------------------------------------------------------
The typical setting for users not interested in troubleshooting the APL
interpreter is to not use any options, i.e:
./configure
The typical setting for software development of the APL interpreter is:
./configure DEVELOP_WANTED=yes
which is a shortcut for:
./configure VALUE_CHECK_WANTED=yes \
VALUE_HISTORY_WANTED=yes \
PERFORMANCE_COUNTERS_WANTED=yes \
DYNAMIC_LOG_WANTED=yes \
ASSERT_LEVEL_WANTED=2
After the first ./configure run (which creates the top level Makefile)
you can do:
make develop
which runs ./configure with the typical development options above.