forked from nasa/GMSEC_API
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathINSTALL.txt
587 lines (416 loc) · 20.3 KB
/
INSTALL.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
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
# Copyright 2007-2020 United States Government as represented by the
# Administrator of The National Aeronautics and Space Administration.
# No copyright is claimed in the United States under Title 17, U.S. Code.
# All Rights Reserved.
=========================================================================
GMSEC API Open Source Build Instructions
=========================================================================
This file describes how to build the GMSEC API from the open source
distribution. The steps in this file assume the user has:
* The source code for the API, located in a directory named GMSEC_API or
GMSEC_API-x.y, where x.y is the version number.
* For Windows systems: Visual Studio 2017
* For all other systems: make and the GNU Compiler Collection
* Red Hat Enterprise Linux 6: gcc 4.4.6, GNU make 3.81 [1]
* Red Hat Enterprise Linux 7: gcc 4.8.5, GNU make 3.82 [1]
* Mac OS X (Intel): gcc LLVM 5.1 (clang-503.0.40), GNU make 3.81
* For Java: Oracle JDK version 1.8 or higher
* For Perl (Windows):
* Strawberry Perl 5.30.1 or later
* SWIG 3.0.10 or later
* the manifest tool (mt.exe) from the Windows SDK
* For Perl (non-Windows):
* (threaded) Perl 5.8.8 or later
* the Simplified Wrapper and Interface Generator (SWIG) 3.0.10
or later
* For Python3:
* Python 3.6 or later
* SWIG 3.0.10 or later
* (non-Windows): python36u package, available through IUS
(https://centos7.iuscommunity.org/ius-release.rpm)
* For C# (non-windows):
* Mono JIT Compiler 5.16.0 or later
Please note that this is intended as a "getting started" document. After
a user becomes familiar with the build process, a more tailored process can be
implemented to fit one's needs.
Comments on dependencies
-----------------------------------------
The tools and versions identified are those used by the GMSEC team to build
binaries for distribution. Many alternative tools and versions will work.
The tools tagged [1] are the defaults shipped on those systems.
Simplified Wrapper and Interface Generator (SWIG) is a third party and open-
source tool used to build the C#, Perl and Python3 language bindings of the
GMSEC API. For users wishing to pursue an open source build of the API, SWIG
will need to be installed in order to build these additional language bindings
of the API.
Building GMSEC API extensions
-----------------------------------------
In order to build GMSEC API extensions, for example middleware adapters,
the directory layout assumed by the build files is:
+ GMSEC_API/
+ ...
+ GMSEC_SUPPORT/
+ ...
For example, if building the middleware adapter for the (fictional) mwx
middleware, the GMSEC_SUPPORT directory would appear as:
+ GMSEC_SUPPORT/
+ mwx/
+ include/
+ lib/
+ ...
where the mwx/include/ and mwx/lib/ directories contain the middleware
client interface and libraries for mwx. Soft-links (or junctions) are useful
when populating the GMSEC_SUPPORT directory since those links can refer to
standard installation locations on the system.
Supported Operating Systems (OSes) include: RHEL6, RHEL7, Ubuntu18.04, MacOS,
and Windows10.
==========================================================================
Windows systems
==========================================================================
Note:
--------------
When building from the Open-Source distribution, the GMSEC_API folder
referenced in the instructions below will actually contain the version
number; for example, GMSEC_API-4.7. Edit the instructions below accordingly.
Environment Variable Settings:
-----------------------------------------
PATH:
Define an environment variable JDK_HOME:
* Set to your Java SDK installation directory (not the bin directory)
Define an environment variable named PERL5_HOME:
* Set to your Perl5 installation directory (not the bin directory)
Define an environment variable named PYTHON_HOME:
* Set to your Python installation directory (not the bin directory)
Define an environment variable named SWIG_HOME:
* Set to your SWIG installation directory (not the bin directory)
Add all of the following to your PATH:
* GMSEC_API\bin (the full path to this directory)
* the path to perl.exe (to build the Perl binding)
* the path to javac (to build the Java binding)
* the .NET Framework 4 directory
* the path to mt.exe (in the Windows SDK)
* Visual Studio 2017's Common7/IDE, VC/Auxiliary/Build, and VC/Tools/MSVC
directories
For example:
set JDK_HOME=C:\Program Files\Java\jdk1.8.0_131
set PERL5_HOME=C:\Perl64
set PYTHON3_HOME=C:\Python3
set SWIG_HOME=C:\swig-3.0.10
set PATH=%PATH%;C:\GMSEC_API\bin;C:\Perl\bin;C:\Program Files\Java\jdk1.8.131\bin;
set PATH=%PATH%;C:\Windows\Microsoft.NET\Framework\v3.5
set PATH=%PATH%;C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\IDE
set PATH=%PATH%;C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build;
C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Tools\MSVC\14.13.26128\bin\Hostx64\x64
Please note that when setting environment variables in this fashion, they will
only be available for any processes that are run within the same command line
window.
To set environment variables so that they affect all processes, open up the
Environment Variables settings in Windows (search for "environment" in the start
menu and add/modify variables as needed*.
Note:
Any open process (e.g. command prompt, cygwin, or Visual Studio) will need to
be restarted if environment variables have been added or modified.
Building the C++, C#, Java, Perl, and Python3 APIs:
---------------------------------------------------
Open GMSEC_API\gmsecapi_opensource.sln in Visual Studio 2017.
Choose the "Release" Solution Configuration (located in the toolbar) and select
the "x64" architecture (note, the GMSEC API no longer supports "Win32" builds).
From the Solution Explorer, right-click the solution and select "Rebuild
Solution".
To build the dotnet project with the solution file, which is needed to
build the C#/CLI API, users will instead need to choose the "Release-SNK"
Solution Configuration, then rebuild the solution.
Users may need to generate a strong-name key file (.SNK) in order to rebuild
with the "Release-SNK" Solution Configuration. To do this, click on the system's
Start menu, then reference Visual Studio 2017, and finally select x64 Native
Tools Command Prompt for VS 2017. From the Command Prompt, navigate to the
GMSEC API extension GMSEC_SUPPORT/windows_snk (users may need to
create this directory). Then execute:
sn -k GMSEC.snk
Building the GMSEC API legacy (3.X) Perl binding:
-------------------------------------------------
At the Windows command prompt, from the GMSEC_API\perl\gmsec directory, execute:
perl -Iextra Makefile.PL PREFIX=..\..\bin
vcvarsall.bat
nmake
nmake install
Utilities (e.g. gmpub, gmsub, etc.):
---------------------
Open GMSEC_API\tools\utilities\utilities.sln in Visual Studio. Choose the
Release configuration. In the Solution Explorer, right-click the solution
and select "Rebuild Solution". (Requires that the C++ API be built.) The
executables will be placed in the GMSEC_API/bin directory.
C++ Examples:
---------------------
Open GMSEC_API\examples\cpp\cpp.sln in Visual Studio. Choose the Release
configuration. In the Solution Explorer, right-click the solution and
select "Rebuild Solution". (Requires that the C++ API be built.) The
executables will be placed in the GMSEC_API/bin directory.
C Examples:
---------------------
Open GMSEC_API\examples\c\c.sln in Visual Studio 2008 Express. Choose the
Release configuration. In the Solution Explorer, right-click the solution
and select "Rebuild Solution". (Requires that the C++ API be built.) The
executables will be placed in the GMSEC_API/bin directory.
C# Examples:
---------------------
Open GMSEC_API\examples\csharp\csharp.sln in Visual Studio. Choose the
Release configuration. In the Solution Explorer, right-click the solution
and select "Rebuild Solution". (Requires that the C++ API be built.) The
executables will be placed in the GMSEC_API/bin directory.
C#/CLI Examples:
---------------------
Open GMSEC_API\examples\csharp-dotnet\cs.sln in Visual Studio. Choose the
Release configuration. In the Solution Explorer, right-click the solution
and select "Rebuild Solution". (Requires that the C++ API be built.) The
executables will be placed in the GMSEC_API/bin directory.
Java Examples:
---------------------
Run GMSEC_API\examples\java\compileAll.cmd
If the builds are successful you will have built the GMSEC API, the Bolt
message delivery server as well as the C and C++ example code. These software
entities will reside in the GMSEC_API\bin directory.
Proceed to the section "Testing the Build" below.
=========================================================================
Linux/macOS systems
=========================================================================
Note:
--------------
When building from the Open-Source distribution, the GMSEC_API folder
referenced in the instructions below will actually contain the version
number; for example, GMSEC_API-4.7. Edit the instructions below accordingly.
Environment Variable Settings:
-----------------------------------------
GMSEC_PLATFORM
--------------
Set the GMSEC_PLATFORM environment variable based on the platform to one
of the following:
Platform Setting
--------- -------
Linux linux.x86_64
macOS macosx.x86_64
JDK PATH:
---------
Set the JDK_HOME environment variable to your JDK installation
e.g. export JDK_HOME=/usr/java/jdk1.8.0_131
For macOS users, here's an example of setting JDK_HOME
e.g. export JDK_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.131.jdk/Contents/Home/
PATH :
------
Ensure that the path to the Perl, Python3, and SWIG executables are set in the
PATH environment variable so that they can be readily accessed via command
line.
Note that if Python, Perl, and SWIG were installed as a default package with the
operating system, then these are already included in /usr/bin and nothing
needs to be done here.
PERL5 LIBRARIES:
--------------------
Set the PERL5_LIB environment variable to the directory containing the library
development files for your installation of Perl 5.
(Note: This directory path may vary between different versions of Perl. The
directory in question contains a subdirectory named "CORE")
e.g. export PERL5_LIB=/usr/lib64/perl5
PYTHON3 DEVELOPMENT HEADERS:
----------------------------
For Python3 support, set PYTHON3_HOME to the location where Python3 development
folder is located. In addition, set PYTHONPATH to reference the appropriate
GMSEC API libraries.
e.g. export PYTHON3_HOME=/usr/local/python3
export PYTHONPATH=/home/user/GMSEC_API/bin:/home/user/GMSEC_API/bin/lib/GMSECAPI4:.
SWIG HOME :
-----------
Set the SWIG_HOME environment variable to your SWIG installation directory
e.g. export SWIG_HOME=/home/user/GMSEC_SUPPORT/swig-3.0.10
MW_WRAPPERS :
-----------
This environment variable can be used to specify which middleware wrappers, in
addition to Message Bus and Bolt wrappers, that should be created. A listing
of the various middleware wrappers that can be built are listed in the
GMSEC_API/wrapper directory.
For example, in Bash, the following statement would indicate that the ActiveMQ
C++ 3.9.5 and the IBM MQ 9.0 wrappers should be built:
export MW_WRAPPERS="activemq395 ibmmq90"
NOTE:
-----
If these environment settings have been added to a file such as ".profile",
".cshrc", or ".bashrc", etc., these will need to resourced in order to
incorporate these settings into the environment.
Building the API :
-----------------------
To begin building the GMSEC API, execute the following commands:
$ cd GMSEC_API
$ make clean && make && make install
If the make-process is successful, the GMSEC API will have been built, along
with a handful of utility executable programs that can be used to test the API.
These software libraries and utilities will reside in the GMSEC_API/bin
directory.
=========================================================================
Testing the Build
=========================================================================
Referencing the GMSEC API libraries:
------------------------------------
The GMSEC_API/bin directory holds shared libraries needed by GMSEC.
The environment variable that specifies the directories to search for
shared libraries depends on the operating system:
Platform Environment Variable
------------- ----------------------
Windows PATH
Linux LD_LIBRARY_PATH
macOS DYLD_LIBRARY_PATH
Update the environment variable corresponding to the platform to include
the fully qualified GMSEC_API/bin directory.
For example:
Windows set PATH=C:\GMSEC\release\GMSEC_API\bin;%PATH%
Linux export LD_LIBRARY_PATH=/home/me/GMSEC/release/GMSEC_API/bin
macOS export DYLD_LIBRARY_PATH=/Users/me/GMSEC/release/GMSEC_API/bin
Linux and macOS users may also wish to include GMSEC_API/bin in their PATH
environment variable; although this is optional, it is highly recommended.
For example:
Linux export PATH=/home/me/GMSEC/release/GMSEC_API/bin:$PATH
macOS export PATH=/Users/me/GMSEC/release/GMSEC_API/bin:$PATH
NOTE:
-----
For macOS users whose system has System Integrity Protection (SIP) enabled,
setting DYLD_LIBRARY_PATH may prove to be moot. Instead, create soft-links
of the GMSEC API libraries in /usr/local/lib and the GMSEC API message templates
one level above.
For example:
$ cd /usr/local/lib
$ sudo ln -s /Users/me/GMSEC_API/bin/*.dylib .
$ sudo ln -s /Users/me/GMSEC_API/bin/*.jnilib .
$ cd /usr/local
$ sudo ln -s /Users/me/GMSEC_API/templates .
Start the Bolt server:
----------------------
Windows java -jar C:\GMSEC\release\GMSEC_API\bin\bolt.jar
Linux java -jar /home/me/GMSEC\release\GMSEC_API\bin\bolt.jar
macOS java -jar /Users/me/GMSEC\release\GMSEC_API\bin\bolt.jar
The Bolt server should indicate that it is listening for a connection, with a
an output message similar to:
2013/347/06:01:10.351 INFO bolt.Server
waiting for connections on /0.0.0.0:9100
Start the GMSEC message subscriber:
-----------------------------------
For all systems:
gmsub mw-id=bolt
The subscriber should estabish a connection and listen for a message for which
it has subscribed. For example:
2013/347/06:02:07.282 INFO bolt.Server
creating IOManager
2013/347/06:02:07.323 MONITOR bolt.Client[id=1]
created
2013/347/06:02:07.342 INFO bolt.IOManager
welcome: added WELCOME to Client[id=1]
Start the GMSEC message publisher:
----------------------------------
For all systems:
gmpub mw-id=bolt
The publisher should connect to Bolt and publish a single message, similar to:
2019-252-12:48:21.874 [INFO] [gmpub.cpp:110] GMSEC API v4.7 [09/09/2019]
2019-252-12:48:21.911 [INFO] [BoltConnection.cpp:239] [0,40,0] : Connection established
2019-252-12:48:21.911 [INFO] [gmpub.cpp:121] Middleware version = Bolt 4.7
2019-252-12:48:21.911 [INFO] [gmpub.cpp:176] Publishing 1 message(s)
2019-252-12:48:21.911 [INFO] [gmpub.cpp:181] Publish interval 1000 [ms]
2019-252-12:48:21.911 [INFO] [gmpub.cpp:182] Message subject 'GMSEC.MSSN.SAT1.MSG.HB.GMPUB'
2019-252-12:48:21.916 [INFO] [gmpub.cpp:284] Published:
<MESSAGE SUBJECT="GMSEC.MSSN.SAT1.MSG.HB.GMPUB" KIND="PUBLISH">
<FIELD NAME="COMPONENT" TYPE="STRING" HEAD="T">GMPUB</FIELD>
<FIELD NAME="CONSTELLATION-ID" TYPE="STRING" HEAD="T">CNS1</FIELD>
<FIELD NAME="CONTENT-VERSION" TYPE="F32" BITS="44FC6000">2019</FIELD>
<FIELD NAME="COUNTER" TYPE="U16">1</FIELD>
<FIELD NAME="DOMAIN1" TYPE="STRING" HEAD="T">DOM1</FIELD>
<FIELD NAME="DOMAIN2" TYPE="STRING" HEAD="T">DOM2</FIELD>
<FIELD NAME="FACILITY" TYPE="STRING" HEAD="T">MY-FACILITY</FIELD>
<FIELD NAME="HEADER-VERSION" TYPE="F32" HEAD="T" BITS="44FC6000">2019</FIELD>
<FIELD NAME="MESSAGE-SUBTYPE" TYPE="STRING" HEAD="T">HB</FIELD>
<FIELD NAME="MESSAGE-TYPE" TYPE="STRING" HEAD="T">MSG</FIELD>
<FIELD NAME="MISSION-ID" TYPE="STRING" HEAD="T">MSSN</FIELD>
<FIELD NAME="PUB-RATE" TYPE="U16">1</FIELD>
<FIELD NAME="SAT-ID-LOGICAL" TYPE="STRING" HEAD="T">SAT1</FIELD>
<FIELD NAME="SAT-ID-PHYSICAL" TYPE="STRING" HEAD="T">SAT1</FIELD>
<FIELD NAME="SPECIFICATION" TYPE="STRING" HEAD="T">GMSEC</FIELD>
</MESSAGE>
2019-252-12:48:22.011 [INFO] [BoltConnection.cpp:231] [0,39,0] : Connection disconnected
=========================================================================
GMSEC API Example Programs
=========================================================================
C++ Examples:
-------------
C++ example programs reside in GMSEC_API/examples/cpp. These are not compiled
as part of the top level API build process, therefore each example program will
need to be compiled by the user using Visual Studio (Windows) or using 'make'
(Linux and macOS).
C Examples:
-----------
C example programs reside in GMSEC_API/examples/c. These are not compiled
as part of the top level API build process, therefore each example program will
need to be compiled by the user using Visual Studio (Windows) or using 'make'
(Linux and macOS).
C# Examples:
------------
C# example programs reside in GMSEC_API/examples/csharp. These are not compiled
as part of the top level API build process, therefore each example program will
need to be compiled by the user using Visual Studio (Windows) or using Mono
Develop (Linux).
C#/CLI Examples:
----------------
C#/CLI example programs reside in GMSEC_API/examples/csharp-dotnet. These are
not compiled as part of the top level API build process, therefore each example
program will need to be compiled by the user using Visual Studio.
Java Examples:
--------------
Java example programs reside in GMSEC_API/examples/java. These are not compiled
as part of the top level API build process, therefore each example program will
need to be compiled by the user. Scripts are provided to facilitate compiling
the example programs.
Perl Examples:
--------------
Perl example programs reside in GMSEC_API/examples/perl. The example programs
are scripts, thus they do not need to be compiled.
Python3 Examples:
-----------------
Python3 example programs reside in GMSEC_API/examples/python3. The example
programs are scripts, thus they do not need to be compiled.
=========================================================================
Runtime Environment
=========================================================================
Note: ROOT-DIR is the full path to where the GMSEC_API is installed. For
example:
ROOT-DIR = C:\GMSEC\
or
ROOT-DIR = ~\GMSEC\
Java Programs:
------------------
In order to run programs with the Java API, the gmsecapi.jar file must be
present in the CLASSPATH.
For example:
Windows set CLASSPATH=<ROOT-DIR>/GMSEC_API/bin/gmsecapi.jar
Linux export CLASSPATH=<ROOT-DIR>/GMSEC_API/bin/gmsecapi.jar
macOS export CLASSPATH=<ROOT-DIR>/GMSEC_API/bin/gmsecapi.jar
Perl Programs:
--------------
In order to run programs with the Perl API, the GMSEC_API/bin and
GMSEC_API/bin/lib/GMSECAPI4 directories must be set in the PERL5LIB
environment variable.
NOTE that this is not the same as the PERL5_LIB variable used
for building the API.
For example:
Windows set PERL5LIB=<ROOT-DIR>/GMSEC_API/bin;<ROOT-DIR>/GMSEC_API/bin/lib/GMSECAPI4
Linux export PERL5LIB=<ROOT-DIR>/GMSEC_API/bin:<ROOT-DIR>/GMSEC_API/bin/lib/GMSECAPI4
macOS export PERL5LIB=<ROOT-DIR>/GMSEC_API/bin:<ROOT-DIR>/GMSEC_API/bin/lib/GMSECAPI4
Python3 Programs:
-----------------
In order to run programs with the Python3 API, the GMSEC_API/bin and
GMSEC_API/bin/lib/GMSECAPI4 directories must be set in the PYTHONPATH
environment variable.
For example:
Windows set PYTHONPATH=<ROOT-DIR>/GMSEC_API/bin;<ROOT-DIR>/GMSEC_API/bin/lib/GMSECAPI4
Linux export PYTHONPATH=<ROOT-DIR>/GMSEC_API/bin:<ROOT-DIR>/GMSEC_API/bin/lib/GMSECAPI4
macOS export PYTHONPATH=<ROOT-DIR>/GMSEC_API/bin:<ROOT-DIR>/GMSEC_API/bin/lib/GMSECAPI4
=========================================================================
Support/Contact Information
=========================================================================
Questions, comments and concerns regarding the GMSEC API Open Source
distribution should be sent to:
gmsec-support@lists.nasa.gov
=========================================================================