-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME_DEVELOPPER.txt
402 lines (338 loc) · 30.1 KB
/
README_DEVELOPPER.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
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
============================================================================================================================================================================
============================================================================================================================================================================
============================================================================================================================================================================
SSSSSSSSSSSSSSS IIIIIIIIII MMMMMMMM MMMMMMMM IIIIIIIIII LLLLLLLLLLL AAA RRRRRRRRRRRRRRRRR
SS:::::::::::::::S I::::::::I M:::::::M M:::::::M I::::::::I L:::::::::L A:::A R::::::::::::::::R
S:::::SSSSSS::::::S I::::::::I M::::::::M M::::::::M I::::::::I L:::::::::L A:::::A R::::::RRRRRR:::::R
S:::::S SSSSSSS II::::::II M:::::::::M M:::::::::M II::::::II LL:::::::LL A:::::::A RR:::::R R:::::R
S:::::S I::::I M::::::::::M M::::::::::M I::::I L:::::L A:::::::::A R::::R R:::::R
S:::::S I::::I M:::::::::::M M:::::::::::M I::::I L:::::L A:::::A:::::A R::::R R:::::R
S::::SSSS I::::I M:::::::M::::M M::::M:::::::M I::::I L:::::L A:::::A A:::::A R::::RRRRRR:::::R
SS::::::SSSSS I::::I M::::::M M::::M M::::M M::::::M I::::I L:::::L A:::::A A:::::A R:::::::::::::RR
SSS::::::::SS I::::I M::::::M M::::M::::M M::::::M I::::I L:::::L A:::::A A:::::A R::::RRRRRR:::::R
SSSSSS::::S I::::I M::::::M M:::::::M M::::::M I::::I L:::::L A:::::AAAAAAAAA:::::A R::::R R:::::R
S:::::S I::::I M::::::M M:::::M M::::::M I::::I L:::::L A:::::::::::::::::::::A R::::R R:::::R
S:::::S I::::I M::::::M MMMMM M::::::M I::::I L:::::L LLLLLL A:::::AAAAAAAAAAAAA:::::A R::::R R:::::R
SSSSSSS S:::::S II::::::II M::::::M M::::::M II::::::II LL:::::::LLLLLLLLL:::::L A:::::A A:::::A RR:::::R R:::::R
S::::::SSSSSS:::::S I::::::::I M::::::M M::::::M I::::::::I L::::::::::::::::::::::L A:::::A A:::::A R::::::R R:::::R
S:::::::::::::::SS I::::::::I M::::::M M::::::M I::::::::I L::::::::::::::::::::::L A:::::A A:::::A R::::::R R:::::R
SSSSSSSSSSSSSSS IIIIIIIIII MMMMMMMM MMMMMMMM IIIIIIIIII LLLLLLLLLLLLLLLLLLLLLLLLAAAAAAA AAAAAAARRRRRRRR RRRRRRR
__ _____ _ _ _ _ _ _ _ _ _____ __ _
/ _\ \_ \_ __ ___ _ _| | __ _| |_(_) ___ _ __ ___ __ _(_) |_| |__ /\/\ _ _| | |_ \_ \ / / _____ _____| |
\ \ / /\/ '_ ` _ \| | | | |/ _` | __| |/ _ \| '_ \/ __| \ \ /\ / / | __| '_ \ / \| | | | | __| / /\/____ / / / _ \ \ / / _ \ |
_\ \/\/ /_ | | | | | | |_| | | (_| | |_| | (_) | | | \__ \ \ V V /| | |_| | | | / /\/\ \ |_| | | |_/\/ /_|_____/ /__| __/\ V / __/ |
\__/\____/ |_| |_| |_|\__,_|_|\__,_|\__|_|\___/|_| |_|___/ \_/\_/ |_|\__|_| |_| \/ \/\__,_|_|\__\____/ \____/\___| \_/ \___|_|
_ _ _ __ _ _
/_\ __ _ ___ _ __ | |_ ___ __ _ _ __ __| | /__\ ___ __ _ ___| |_(_) ___ _ __ ___
//_\\ / _` |/ _ \ '_ \| __/ __| / _` | '_ \ / _` | / \/// _ \/ _` |/ __| __| |/ _ \| '_ \/ __|
/ _ \ (_| | __/ | | | |_\__ \ | (_| | | | | (_| | / _ \ __/ (_| | (__| |_| | (_) | | | \__ \
\_/ \_/\__, |\___|_| |_|\__|___/ \__,_|_| |_|\__,_| \/ \_/\___|\__,_|\___|\__|_|\___/|_| |_|___/
|___/
ASCII fonts obtained using the "Doh", "Ogre" and "Graceful" fonts in the "http://patorjk.com/software/taag/" website.
============================================================================================================================================================================
============================================================================================================================================================================
___
| __ _|_ __ _ _| _ _|_ o _ __
_|_| | |_ | (_)(_||_|(_ |_ | (_)| |
============================================================================================================================================================================
This project is the root Maven project of the SIMILAR API suite.
The SIMILAR suite is a java API whose purpose is to support the implementation of multi-agent-based simulations using the formerly named IRM4MLS meta-model.
This software defines an API to implement such simulations and provides usage examples.
The structure of the project as well as the user and developer documentation are defined in the documentation of the project.
The section (II-c) of this README file tells how the documentation can be generated using Maven.
Summary:
I - Installation instructions (sum-inst)
a - Prerequisites (sum-requ)
b - Install Maven (sum-mave)
1 - Installation instructions (sum-mavi)
2 - Proxy settings (sum-prox)
3 - Installation verification (sum-veri)
4 - Using local libraries (sum-locl)
5 - Eclipse integration (sum-ecli)
II - Components generation (sum-comp)
a - Clean generated files (sum-clea)
b - Generate the jar archives (sum-jars)
c - Run stand-alone unit tests (sum-test)
III - Deployment (sum-depl)
IV - Editing the SIMILAR API suite (sum-edit)
a - Including license information (sum-incl)
b - Changing the version number (sum-vers)
c - Adding simulation examples (sum-exam)
d - Updating the documentation (sum-docu)
V - Copyrighting (sum-copy)
--- (sum-inst) =============================================================================================================================================================
___ ___
| --- | __ _ _|_ _ | | _ _|_ o _ __ o __ _ _|_ __ _ _|_ o _ __ _
_|_ _|_| |_> |_(_| | | (_| |_ | (_)| | | | |_> |_ | |_|(_ |_ | (_)| |_>
============================================================================================================================================================================
Since the SIMILAR API suite is a Java-based technology, a valid J2SE SDK has to be installed on the computer. SIMILAR was designed with the oracle implementation of the
Java Virtual Machine and compilation tools, with the version numbers:
- Java(TM) SE Runtime Environment (build 1.8.0_25-b17)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
(I-a) Prerequisites (sum-requ)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
As we said in the beginning of this section, this project uses java. Thus a working installation of java is necessary. In addition, to facilitate the use of the
command line operators, the 'JAVA_HOME' environment variable has to be set to the appropriate value (the root directory of the installed SDK), and the binaries directory
of the java installation has to be included into the system 'PATH' environment variable.
In Windows, it means to add to the end of the 'PATH' environment variable the text following text, without the quote marks: ";%JAVA_HOME%\bin"
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
(I-b) Install Maven (sum-mave)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The SIMILAR API suite relies on the Maven project management tool to build the project and generate the jar API.
Since Maven is a Java tool, a Java SDK has to be installed on the machine to perform the following Maven installation operations. The installation instructions of Maven
are listed in the following website: "http://maven.apache.org/download.cgi#Installation".
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
(I-b-1) Installation instructions (sum-mavi)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
This readme file includes the installation instructions that were used to install it onto a Windows machine:
- Download Maven at the "http://maven.apache.org/download.cgi" page
- Unpack the downloaded archive in a directory of the file system.
This directory will be called $MAVEN_HOME from now on.
- Create a 'M2_HOME' environment variable containing the $MAVEN_HOME value.
This value should NOT end with a '\' character.
- Add the text ";%M2_HOME%\bin" (without quotes) to the end of the 'PATH' environment variable.
After these instructions, the "mvn" operation can be performed using a command line prompt.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
(I-b-2) Proxy settings (sum-prox)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
If you are using a proxy to connect to the internet, Maven still cannot be used to manage the project. Indeed, Maven uses the internet connection to download all the
dependencies of the project. Since manually adding all the dependencies is time consuming, it is better to configure Maven to use your internet proxy. This task is
achieved with the following instructions:
- Open the $Maven_HOME\config\settings.xml file.
- Search for the 'proxies' tag.
- Add the following text between the 'proxies' tag:
<proxy>
<id>a-unique-proxy-id</id>
<active>true</active>
<protocol>http</protocol>
<host>the-adress-of-the-proxy-as-an-ip-adress-or-an-http-adress</host>
<port>the-connection-port-of-the-proxy</port>
<nonProxyHosts>localhost</nonProxyHosts>
</proxy>
If during the execution of a maven target, the execution of maven is temporarily waiting during each download instruction, your computer is most likely using a proxy to
connect to the internet. In such situations, please follow the above-mentionned instructions to set the proxy in the configuration of Maven.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
(I-b-3) Installation verification (sum-veri)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The appropriate installation of Maven can be checked by perfoming two tests. The first one checks that the 'mvn' command is recognized by the system. The second one
checks that dependencies can be downloaded from the internet.
First test:
Type the "mvn --version" command in a command line prompt. It should print information looking like the following text:
Apache Maven 3.3.9 (bb52d8502b132ec0a5a3f4c09453c07478323dc5; 2015-11-10T17:41:47+01:00)
Maven home: /opt/local/share/java/maven3
Java version: 1.8.0_25, vendor: Oracle Corporation
Java home: /Library/Java/JavaVirtualMachines/jdk1.8.0_25.jdk/Contents/Home/jre
Default locale: fr_FR, platform encoding: UTF-8
OS name: "mac os x", version: "10.11.4", arch: "x86_64", family: "mac"
Second test:
Create a temporary directory on the file system, and open a command line prompt inside it. Then type the following command:
"mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false"
The execution of that command might take a while the first time, since Maven will download a lot of dependencies. Look at the end of the printed trace. It should mention
that the build was a success. Otherwise, see the section about proxies settings (sum-prox).
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
(I-b-4) Using local libraries (sum-locl)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
This step is not necessary in SIMILAR since it does not use libraries that cannot be found in the central repository of Maven.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
(I-b-5) Eclipse integration (sum-ecli)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Different eclipse plugins can integrate Maven. The SIMILAR suite was designed using the "m2e" eclipse plugin.
Its lastest release can be found at the following website: "http://download.eclipse.org/technology/m2e/releases".
Once installed, you have to update the configuration of the m2e plugin to ensure that eclipse uses your Maven installation rather than the default integrated one. This
task is achieved using the following instructions:
- Open the 'Window' menu of the top menu bar of eclipse.
- Select the 'Preferences' item of that menu.
- In the opened popup, expand the 'Maven' menu of the left tabbed pane.
- Select the 'Installation' item of the expanded menu.
- In the opened panel to the right, select the 'Add' button.
- Select the $MAVEN_HOME directory in the opened popup and then validate.
- Check that the text field at the bottom displays the '$MAVEN_HOME\conf\settings.xml' value.
- Otherwise, select the "User Settings" menu item on the left
- On the right of the 'User Settings (open file):' label, select the 'Browse...' button
- Choose the '$MAVEN_HOME\conf\settings.xml' file in the opened popup.
- Apply the changes and close the Preferences popup.
--- (sum-comp) =============================================================================================================================================================
______ __
| | --- / _ __ _ _ __ _ __ _|_ _ _ _ __ _ __ _ _|_ o _ __
_|__|_ \__(_)||||_)(_)| |(/_| | |__> (_|(/_| |(/_ | (_| |_ | (_)| |
| __|
============================================================================================================================================================================
The generation of the different components of the SIMILAR API suite is achieved automatically and recursively. Therefore, you don't have to perform these operations
for each Maven sub-module of the project.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
(II-a) Clean generated files (sum-clea)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The following instructions tell how to remove all the generated files from the project and all of its sub-modules:
- Using the command line:
- Go into the root directory of the project
- Run the 'mvn clean' command
- Using eclipse:
- Right click on the project in the file or the package explorer
- Hover the 'Run As' menu and select the 'Maven clean' item (the fifth one)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
(II-b) Generate the jar archives (sum-jars)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The following instructions tell how to compile and pack the project into a jar archive that can be used to create simulations with Similar. The generated archives are
located into the 'target' directory of each sub-module. To generate a stand alone archive, refer to the deployment section (sum-depl).
Note that the following command will also run the unit tests on the project.
- Using the command line:
- Go into the root directory of the project
- Run the 'mvn install' command
- Using eclipse:
- Right click on the project in the file or the package explorer
- Using the command line:
- Go into the root directory of the project
- Run the "mvn -Dmaven.test.skip=true install" command
- Using eclipse:
- Right click on the project in the file or the package explorer
- Hover the 'Run As' menu and select the 'Maven build...' item (the fourth one)
- Enter an explicit name to this eclipse run configuration, in the text field at the top. For instance 'SIMILAR - all - package'
- Type the 'install' text into the text field right to the 'Goals' text field.
- Select the 'Run' button located at the bottom right of the frame.
The next time this operation has to be done, you have only to select the 'SIMILAR - all - package - noTest' build configuration and click on the 'Run' button.
To pack the application without running the tests, use the following instructions:
- Using the command line:
- Go into the root directory of the project
- Run the "mvn -Dmaven.test.skip=true install" command
- Using eclipse:
- Right click on the project in the file or the package explorer
- Hover the 'Run As' menu and select the 'Maven build...' item (the fourth one)
- Enter an explicit name to this eclipse run configuration, in the text field at the top. For instance 'SIMILAR - all - package - noTest'
- Type the 'install' text into the text field right to the 'Goals' text field.
- Select the 'Add...' button at the center right of the frame.
- Type the 'maven.test.skip' text in the field next to the 'Name:' label and the 'true' text in the field next to the 'Value:' label
- Select the 'Run' button located at the bottom right of the frame.
The next time this operation has to be done, you have only to select the 'SIMILAR - all - package - noTest' build configuration and click on the 'Run' button.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
(II-c) Run stand-alone unit tests (sum-test)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The following instruction tell how to run tests on the application for the whole SIMILAR suite without generating the jar archives:
- Using the command line:
- Go into the root directory of the project
- Run the 'mvn test' command
- Using eclipse:
- Right click on the project in the file or the package explorer
- Hover the 'Run As' menu and select the 'Maven test' menu (the eighth one)
--- (sum-depl) =============================================================================================================================================================
_________ _
| | | --- | \ _ _ | _ __ _ __ _|_
_|__|__|_ |_/(/_|_) | (_) \/|||(/_| | |_
| /
============================================================================================================================================================================
A maven instruction is set in this project to build a binary archive containing the jar files of the SIMILAR API suite, its jar dependencies, the documentation, some
examples and all the other resources required by the SIMILAR API suite to work. This archive is built using the following instructions. Note that these instructions
include the unit tests of the API suite. To avoid them, see the next paragraph of this section:
- Using the command line:
- Go into the root directory of the project
- Run the "mvn clean install" command
- Using eclipse:
- Right click on the project in the file or the package explorer
- Hover the 'Run As' menu and select the 'Maven build...' item (the fourth one)
- Enter an explicit name to this eclipse run configuration, in the text field at the top. For instance 'SIMILAR - binary archive'
- Type the 'clean install' text into the text field right to the 'Goals' text field.
- Select the 'Run' button located at the bottom right of the frame.
The next time this operation has to be done, you have only to select the 'SIMILAR - all - package - noTest' build configuration and click on the 'Run' button.
To avoid the unit tests during that process, the following instructions have to be used:
- Using the command line:
- Go into the root directory of the project
- Run the "mvn -Dmaven.test.skip=true clean install" command
- Using eclipse:
- Right click on the project in the file or the package explorer
- Hover the 'Run As' menu and select the 'Maven build...' item (the fourth one)
- Enter an explicit name to this eclipse run configuration, in the text field at the top. For instance 'SIMILAR - binary archive - no tests'
- Type the 'clean install' text into the text field right to the 'Goals' text field.
- Select the 'Add...' button at the center right of the frame.
- Type the 'maven.test.skip' text in the field next to the 'Name:' label and the 'true' text in the field next to the 'Value:' label
- Select the 'Run' button located at the bottom right of the frame.
The generated binary archive is located in the 'similar-distribution/target' directory.
--- (sum-edit) =============================================================================================================================================================
___ __ _____ ___ _ _ _ _ ___
| \ / --- |_ _| o _|_ o __ _ _|_|_ _ (_ | |V| | | |_||_) |_||_) | _ o _|_ _
_|_ v |__(_| | |_ | | |(_| |_| |(/_ __)_|_| |_|_|__| || \ | || _|_ _> |_| | |_(/_
__|
============================================================================================================================================================================
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
(IV-a) Including license information (sum-incl)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Since we have to include the licensing information in each generated java class, an eclipse code template is defined for that purpose in the "codetemplatex.xml"
file of the parent project of the SIMILAR API suite (artifactId "similar", groupId "fr.univ_artois.lgi2a"). If you are not using eclipse, then add a text has to be added manually
at the beginning of each java file you are writing inside the SIMILAR API suite.
The licensing text to put as a comment at the beginning of the files can be found in the 'LICENSE.txt' file.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
(IV-b) Changing the version number (sum-vers)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
To change the version number of the SIMILAR API suite, the following modifications have to be made:
- Change the version in the 'pom.xml' file of the root of the project:
- Change the value of the "version" tag located in the root of the pom.
- Change the value of the "fr.univ_artois.lgi2a.similar.version" tag located in the "properties" tag of the root of the pom.
- Change the version number of the parent of each 'pom.xml' of the sub-modules, i.e. change version in:
<parent>
<groupId>fr.univ_artois.lgi2a</groupId>
<artifactId>similar</artifactId>
<version>0.0.0</version>
</parent>
- Change the version number in the documentation in the file "src/doc/README.txt":
- Go to the top right of the page and select "backstage"
- In the top menu, select "plugins" and then "SimilarVersionPlugin"
- Click on "Close" at the top right of the page
- Select the "Edit" menu displayed right to the "SimilarVersionPlugin" title
- Find the line starting with "wikify" and change the version number there
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
(IV-c) Adding simulation examples (sum-exam)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The addition of simulation examples has to be made either inside the "src/main/java" of the "similar-microKernel-examples" or "similar-extendedKernel-examples"
sub-modules. They should be located in the same root package than the other examples. In addition, two operations have to be made to include the examples in the
binary distribution:
- A documentation readme file has to be included in the "src/main/doc" directory
- The "src/assembly/similar.xml" file from the "similar-distribution" sub-module has to be edited. A block like the following one has to be happened to the end
of the file (example of the micro-kernel):
<!-- Add the "Trace usage" simulation example -->
<fileSet>
<directory>../similar-microKernel-examples/src/main/java</directory>
<outputDirectory>/examples/microKernel/traceUsage/src</outputDirectory>
<excludes>
<exclude>package-info.java</exclude>
</excludes>
<includes>
<include>**/microkernel/examples/traceusage1/**</include>
</includes>
</fileSet>
<fileSet>
<directory>../similar-microKernel-examples/src/main/doc/</directory>
<outputDirectory>/examples/microKernel/traceUsage</outputDirectory>
<includes>
<include>traceUsage_example_README.txt</include>
</includes>
</fileSet>
In the case of the extended kernel, the block becomes:
<!-- Add the "Trace usage" simulation example -->
<fileSet>
<directory>../similar-extendedKernel-examples/src/main/java</directory>
<outputDirectory>/examples/extendedKernel/traceUsage/src</outputDirectory>
<excludes>
<exclude>package-info.java</exclude>
</excludes>
<includes>
<include>**/extendedKernel/examples/traceusage1/**</include>
</includes>
</fileSet>
<fileSet>
<directory>../similar-extendedKernel-examples/src/main/doc/</directory>
<outputDirectory>/examples/extendedKernel/traceUsage</outputDirectory>
<includes>
<include>traceUsage_example_README.txt</include>
</includes>
</fileSet>
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
(IV-d) Updating the documentation (sum-docu)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The documentation uses the Tiddlywiki format, and is located in the "src/doc" directory of the root module of this project. Note that the modifications
to the documentation are taken into accound only if they are saved using the "save" option of the backstage bar. To show the backstage bar, click on the black button
appearing when the mouse cursor hovers the top right corner of the page.
--- (sum-copy) =============================================================================================================================================================
__
\ / --- / _ _ __ o _ |_ _|_ o __ _
v \__(_)|_) \/ | | (_|| | |_ | | |(_|
| / __| __|
============================================================================================================================================================================
The SIMILAR API suite is under the CECILL-B licence. See the LICENCE.txt (or the documentation) file for more information.