0001 Building Enduro/X On Oracle Solaris Platform
0002 ============================================
0003 :doctype: book
0004
0005 == About manual
0006
0007 This manual describes how to build 'Enduro/X' Oracle Solaris platform.
0008 Document is based on Solaris 11 on x86 machine. Compiler used to Enduro/X is GCC.
0009
0010 == Overview
0011
0012 This manual includes basic installation of Enduro/X which does not
0013 include building of documentation.
0014
0015 Enduro/X on Solaris platform is Using System V message queues.
0016
0017
0018 == Operating System Configuration
0019
0020 For OS configuration settings
0021 see ex_adminman(guides)(Enduro/X Administration Manual, Setup System chapter).
0022 This step is mandatory be executed, before continuing.
0023
0024 == Installation process
0025
0026 The installation process will install required pen source packages from
0027 'http://www.opencsw.org'. You may install packages with different approach.
0028 This is just a sample process for getting build system working on under Solaris.
0029 For getting Enduro/X to work basically we need following packages:
0030
0031 . git
0032
0033 . cmake
0034
0035 . flex
0036
0037 . bison
0038
0039 . libxml2
0040
0041 . gcc/g++
0042
0043 === Packages to be installed
0044
0045 The following operations will be done from root user. This will download
0046 and install open source packages to local machine:
0047
0048 ---------------------------------------------------------------------
0049 $ su - root
0050 # pkgadd -d http://get.opencsw.org/now
0051 # /opt/csw/bin/pkgutil -U
0052 # /opt/csw/bin/pkgutil -y -i git libxml2_dev flex bison cmake gmake
0053 ---------------------------------------------------------------------
0054
0055 === If installing GCC...
0056
0057 ---------------------------------------------------------------------
0058 $ su - root
0059 # /opt/csw/bin/pkgutil -y -i gcc4core gcc4g++
0060 ---------------------------------------------------------------------
0061
0062 === If installing Sun Studio (on Solaris 11)...
0063
0064 - According to: https://pkg-register.oracle.com/register/product_info/6/
0065
0066 - Register and request access, download the
0067 and pkg.oracle.com.key.pem pkg.oracle.com.certificate.pem from Oracle
0068 to server.
0069
0070 Installation shows process for 12.4 version, but any later available should
0071 be installed. Also note that *.profile* and *$HOME/ndrx_home* later needs to
0072 match the path, for example */opt/developerstudio12.6*.
0073
0074 ---------------------------------------------------------------------
0075 $ su - root
0076 # mkdir -m 0775 -p /var/pkg/ssl
0077 # cp -i download-directory/pkg.oracle.com.key.pem /var/pkg/ssl
0078 # cp -i download-directory/pkg.oracle.com.certificate.pem /var/pkg/ssl
0079
0080 # pkg set-publisher \
0081 -k /var/pkg/ssl/pkg.oracle.com.key.pem \
0082 -c /var/pkg/ssl/pkg.oracle.com.certificate.pem \
0083 -G '*' -g https://pkg.oracle.com/solarisstudio/release solarisstudio
0084
0085 # pkg list -af 'pkg://solarisstudio/developer/solarisstudio-124/*'
0086
0087 # pkg install -nv solarisstudio-124
0088
0089 # pkg install solarisstudio-124
0090 ---------------------------------------------------------------------
0091
0092 If plan to run
0093
0094 === If installing Sun Studio (on Solaris 10)...
0095
0096 Firstly download the "tarfile" version from Oracle, visit
0097 http://www.oracle.com/technetwork/server-storage/solarisstudio/downloads/tarfiles-studio-12-4-3048109.html
0098
0099 Next once the tar file is on your server, extract it and start the install:
0100
0101 ---------------------------------------------------------------------
0102 # bzip2 -d SolarisStudio12.4-solaris-x86-bin.tar.bz2
0103 # tar -xf SolarisStudio12.4-solaris-x86-bin.tar
0104 # cd SolarisStudio12.4-solaris-x86-bin
0105 # ./install_patches.sh
0106 # mv solarisstudio12.4 /opt
0107 ---------------------------------------------------------------------
0108
0109 For Solaris 10 also we need gmake to work as "make", thus
0110 ---------------------------------------------------------------------
0111 # ln -s /opt/csw/bin/gmake /usr/bin/make
0112 ---------------------------------------------------------------------
0113
0114 This will put the compiler in "/opt/solarisstudio12.4" the path later used in
0115 this tutorial.
0116
0117 Also for solaris 10 we need "ar" tool which we will use from GNU package:
0118
0119 ---------------------------------------------------------------------
0120 # /opt/csw/bin/pkgutil -y -i gcc4core gcc4g++
0121 ---------------------------------------------------------------------
0122
0123 == Getting the source code
0124
0125 Firstly we need to add "user1" under which we will perform build actions.
0126 For test purposes we will parepare new user for which Enduro/X will built
0127 (this adds the in the path the /opt/csw/bin. You may modify that of your needs.
0128 (add /opt/solarisstudio12.4/bin if Sun studio is installed)
0129
0130 === Adding user on Solaris 11
0131 We add the user "user1" and also set the open file limit to 4096, by
0132 default it is 256 which is too low for unit testing.
0133
0134 ---------------------------------------------------------------------
0135 $ su - root
0136 # useradd -m user1
0137 # passwd user1
0138 # projadd -K "process.max-file-descriptor=(basic,10000,deny)" enduroxproject
0139 # usermod -K "project=enduroxproject" user1
0140 # su - user1
0141 ---------------------------------------------------------------------
0142
0143 === Adding user on Solaris 10
0144
0145 ---------------------------------------------------------------------
0146 $ su - root
0147 # useradd -d \$HOME -m -s /usr/bin/bash -c "User1 User1" user1
0148 # mkdir \$HOME
0149 # chown user1:staff \$HOME
0150 # su - user1
0151 ---------------------------------------------------------------------
0152
0153 === Preparing the user environment
0154
0155 ---------------------------------------------------------------------
0156
0157 $ bash
0158 $ cat << EOF >> .profile
0159 export PATH=\$PATH:/opt/csw/bin:/opt/solarisstudio12.4/bin
0160 # Needed if building with postgres...
0161 export LD_LIBRARY_PATH=\$LD_LIBRARY_PATH:/opt/csw/lib/64
0162 EOF
0163 $ chmod +x .profile
0164 $ source .profile
0165 $ cd \$HOME
0166 $ GIT_SSL_NO_VERIFY=true git clone https://github.com/endurox-dev/endurox
0167 $ cd endurox
0168 $ git config http.sslVerify "false"
0169 ---------------------------------------------------------------------
0170
0171 === Enduro/X basic Environment configuration for HOME directory
0172
0173 This code bellow creates 'ndrx_home' executable file which loads basic environment,
0174 so that you can use sample configuration provided by Enduro/X in 'sampleconfig' directory.
0175 This also assumes that you are going to install to '$HOME/endurox/dist' folder.
0176 The file bellow will override the sample configuration.
0177
0178 ---------------------------------------------------------------------
0179 $ cat << EOF > $HOME/ndrx_home
0180 #!/bin/bash
0181
0182 echo "Loading ndrx_home..."
0183 # Where app domain lives
0184 export NDRX_APPHOME=$HOME/endurox
0185 # Where NDRX runtime lives
0186 export NDRX_HOME=\$HOME/endurox/dist
0187 # Debug config too
0188 export NDRX_DEBUG_CONF=\$HOME/endurox/sampleconfig/debug.conf
0189 # NDRX config too.
0190 export NDRX_CONFIG=\$HOME/endurox/sampleconfig/ndrxconfig.xml
0191
0192 export FLDTBLDIR=\$HOME/endurox/ubftest/ubftab
0193
0194 export PATH=/usr/bin:/usr/sbin:/opt/csw/bin:/opt/solarisstudio12.4/bin:/opt/csw/bin:\$HOME/endurox/dist/bin
0195 export LD_LIBRARY_PATH=/usr/lib/sparcv9:\$HOME/endurox/dist/lib64:/opt/solarisstudio12.4/lib:/usr/lib64:/usr/lib/64:/opt/csw/lib/64
0196
0197 ################################################################################
0198 # In case if building with Postgresql DB database testing support
0199 # or building endurox-java with Oracle DB tests (03_xapostgres), then
0200 # configure bellow setting (demo values provided):
0201 # If so - uncomment bellow
0202 ################################################################################
0203 #export EX_PG_HOST=localhost
0204 #export EX_PG_USER=exdbtest
0205 #export EX_PG_PASS=exdbtest1
0206 # currently uses default port
0207 #export EX_PG_PORT=5432
0208 #export EX_PG_DB=xe
0209
0210 #
0211 # If using PostgreSQL for Solaris 11 uncomment:
0212 #
0213 #export PATH=$PATH:/opt/csw/libexec/postgresql/93
0214
0215
0216 EOF
0217
0218 $ chmod +x $HOME/ndrx_home
0219 ---------------------------------------------------------------------
0220
0221 === Configuring PostgreSQL
0222
0223 If Enduro/X PostgreSQL driver is needed to be build for AIX, the PostgreSQL
0224 needs to be installed for build and test purposes. On Solaris 10, PostgreSQL
0225 comes with the operating system, thus only access rights and users needs to be
0226 configured.
0227
0228 Note if you plan to use ECPG mode, then ecpg pre-compiler needs to know where
0229 the ecpg libraries live. Thus LD_LIBRARY_PATH must be set during the build time.
0230
0231 It can be done in following way:
0232
0233 --------------------------------------------------------------------------------
0234
0235 # su - user1
0236 $ cat << EOF >> .profile
0237 export LD_LIBRARY_PATH=/opt/csw/lib/amd64
0238 EOF
0239
0240 --------------------------------------------------------------------------------
0241
0242 after this login and log out from user1 to apply the .profile settings.
0243
0244 Also to active the PostgreSQL inclusion to the build, add *-DENABLE_POSTGRES=ON*
0245 flag to cmake command line (later in build section).
0246
0247 For Solaris 11 it needs to be installed:
0248
0249 --------------------------------------------------------------------------------
0250
0251 $ su - root
0252
0253 -- Install with:
0254 # /opt/csw/bin/pkgutil -y -i postgresql93
0255
0256 -- Install dev
0257 # /opt/csw/bin/pkgutil -y -i postgresql_dev
0258
0259 -- enable for auto start
0260 # svcadm enable cswpostgresql-93
0261
0262 # su - postgres
0263
0264 -- Create profile entry to have path to postgres binaries
0265
0266 $ cat << EOF > ~/.profile
0267
0268 #!/bin/bash
0269
0270 export PATH=$PATH:/opt/csw/libexec/postgresql/93/
0271
0272 EOF
0273
0274 $ chmod +x ~/.profile
0275
0276 -- Start postgres from Postgres user
0277 $ /opt/csw/bin/pg_ctl-93 -D /var/opt/csw/postgresql/93 -l logfile start
0278 server starting
0279
0280
0281
0282 --------------------------------------------------------------------------------
0283
0284 For Solaris 10, just enable it:
0285
0286 --------------------------------------------------------------------------------
0287
0288 $ su - root
0289 # svcadm enable svc:/application/database/postgresql:version_82
0290
0291 --------------------------------------------------------------------------------
0292
0293 Now create the database for Enduro/X tests (Solaris 10 & 11):
0294
0295 --------------------------------------------------------------------------------
0296 # su - postgres
0297
0298 $ createuser exdbtest
0299
0300 $ createdb xe
0301
0302 $ psql -d template1
0303
0304 > alter user exdbtest with encrypted password 'exdbtest1';
0305 > grant all privileges on database xe to exdbtest;
0306 > \q
0307
0308 --------------------------------------------------------------------------------
0309
0310 Configuration files needs to be updated for authentication and distributed
0311 transactions must be enabled too.
0312
0313 Edit *postgresql.conf*, set "max_prepared_transactions"
0314 to 1000.
0315
0316 Solaris 10: */var/postgres/8.2/data/postgresql.conf*
0317
0318 Solaris 11(.4): */var/opt/csw/postgresql/93/postgresql.conf*
0319
0320 --------------------------------------------------------------------------------
0321
0322 max_prepared_transactions = 1000 # zero disables the feature
0323
0324 --------------------------------------------------------------------------------
0325
0326 For access permissions and network configuration, update
0327 *pg_hba.conf*, so that it contains following:
0328
0329 Solaris 10: */var/postgres/8.2/data/pg_hba.conf*
0330
0331 Solaris 11: */var/opt/csw/postgresql/93/pg_hba.conf*
0332
0333 --------------------------------------------------------------------------------
0334
0335 local all all trust
0336 host all all 127.0.0.1/32 md5
0337 host all all ::1/128 md5
0338
0339 --------------------------------------------------------------------------------
0340
0341 Restart PostgreSQL, Solaris 10:
0342
0343 --------------------------------------------------------------------------------
0344
0345 # svcadm restart svc:/application/database/postgresql:version_82
0346
0347 --------------------------------------------------------------------------------
0348
0349 Restart PostgreSQL, Solaris 11:
0350
0351 --------------------------------------------------------------------------------
0352
0353 # svcadm restart cswpostgresql-93
0354
0355 --------------------------------------------------------------------------------
0356
0357 == Building the code with GCC
0358
0359 It is assumed that gcc is default compiler on the system (i.e. Oracle Studio not installed),
0360 thus following cmake will pick up gcc by default:
0361
0362 === Solaris 11
0363
0364 ---------------------------------------------------------------------
0365 $ cd \$HOME/endurox
0366 $ cmake -DCMAKE_CXX_COMPILER=g++ -DCMAKE_C_COMPILER=gcc\
0367 -DDEFINE_DISABLEDOC=ON -DCMAKE_INSTALL_PREFIX:PATH=`pwd`/dist -DCMAKE_LIBRARY_PATH=/opt/csw/lib/amd64 .
0368 $ make
0369 $ make install
0370 ---------------------------------------------------------------------
0371
0372 === Solaris 10
0373
0374 Also note that CC variable needs to be exported as it is used by
0375 buildclient script for view test cases.
0376
0377 ---------------------------------------------------------------------
0378 $ export CC=gcc
0379 $ cd \$HOME/endurox
0380 $ cmake -D CMAKE_AR=/opt/csw/gnu/ar -DCMAKE_CXX_COMPILER=g++ -DCMAKE_C_COMPILER=gcc \
0381 -DDEFINE_DISABLEDOC=ON -DCMAKE_INSTALL_PREFIX:PATH=`pwd`/dist .
0382 $ make
0383 $ make install
0384 ---------------------------------------------------------------------
0385
0386
0387 == Building the code with Solaris Studio
0388
0389 The compilation will be done in 64bit mode
0390
0391 === Solaris 11
0392
0393 ---------------------------------------------------------------------
0394 $ cd \$HOME/endurox
0395 $ cmake -DCMAKE_INSTALL_PREFIX:PATH=`pwd`/dist -DDEFINE_DISABLEDOC=ON .
0396 ---------------------------------------------------------------------
0397
0398 In case if errors like
0399
0400 ---------------------------------------------------------------------
0401 ld: fatal: file /usr/lib/values-xpg6.o: wrong ELF class: ELFCLASS32
0402 ---------------------------------------------------------------------
0403
0404 appears, temporary solution is to replace that particular file with 64bit version.
0405 It appears that Solaris Studio compiler ignores the "-m64" architecture flags
0406 and does not use "/usr/lib/amd64/values-xpg6.o" where it requires.
0407
0408 ---------------------------------------------------------------------
0409 # su - root
0410 # mv /usr/lib/values-xpg6.o /usr/lib/values-xpg6.o.OLD
0411 # ln -s /usr/lib/amd64/values-xpg6.o /usr/lib/values-xpg6.o
0412 ---------------------------------------------------------------------
0413
0414 === Solaris 10 (NOT SUPPORTED)
0415
0416 This assumes that GCC is installed, and "ar" from gcc will be used.
0417
0418 ---------------------------------------------------------------------
0419 $ cd \$HOME/endurox
0420 $ cmake -D CMAKE_AR=/opt/csw/gnu/ar \
0421 -DCMAKE_INSTALL_PREFIX:PATH=`pwd`/dist -DDEFINE_DISABLEDOC=ON .
0422 ---------------------------------------------------------------------
0423
0424 The support is not available for Solaris Studio on Solaris 10 due
0425 to Thread Local Storage errors like during the linking:
0426
0427 ---------------------------------------------------------------------
0428 ld: fatal: relocation error: R_SPARC_TLS_LDO_LOX10: file CMakeFiles/nstd.dir/ndebug.c.o: symbol $XBaBAqASPv3bHaz.__ndrx_debug__.first: bound to: CMakeFiles/nstd.dir/ndebug.c.o: relocation illegal when not bound to object being created
0429 ld: fatal: relocation error: R_SPARC_TLS_LDO_ADD: file CMakeFiles/nstd.dir/ndebug.c.o: symbol $XBaBAqASPv3bHaz.__ndrx_debug__.first: bound to: CMakeFiles/nstd.dir/ndebug.c.o: relocation illegal when not bound to object being created
0430 ld: fatal: relocation error: R_SPARC_TLS_LDO_HIX22: file CMakeFiles/nstd.dir/ndebug.c.o: symbol $XBaBAqASPv3bHaz.__ndrx_debug__.ostid: bound to: CMakeFiles/nstd.dir/ndebug.c.o: relocation illegal when not bound to object being created
0431 ld: fatal: relocation error: R_SPARC_TLS_LDO_LOX10: file CMakeFiles/nstd.dir/ndebug.c.o: symbol $XBaBAqASPv3bHaz.__ndrx_debug__.ostid: bound to: CMakeFiles/nstd.dir/ndebug.c.o: relocation illegal when not bound to object being created
0432 ld: fatal: relocation error: R_SPARC_TLS_LDO_ADD: file CMakeFiles/nstd.dir/ndebug.c.o: symbol $XBaBAqASPv3bHaz.__ndrx_debug__.ostid: bound to: CMakeFiles/nstd.dir/ndebug.c.o: relocation illegal when not bound to object being created
0433 ld: fatal: relocation error: R_SPARC_TLS_LDO_HIX22: file CMakeFiles/nstd.dir/ndebug.c.o: symbol $XBaBAqASPv3bHaz.__ndrx_debug__.ostid: bound to: CMakeFiles/nstd.dir/ndebug.c.o: relocation illegal when not bound to object being created
0434 ld: fatal: relocation error: R_SPARC_TLS_LDO_LOX10: file CMakeFiles/nstd.dir/ndebug.c.o: symbol $XBaBAqASPv3bHaz.__ndrx_debug__.ostid: bound to: CMakeFiles/nstd.dir/ndebug.c.o: relocation illegal when not bound to object being created
0435 ld: fatal: relocation error: R_SPARC_TLS_LDO_ADD: file CMakeFiles/nstd.dir/ndebug.c.o: symbol $XBaBAqASPv3bHaz.__ndrx_debug__.ostid: bound to: CMakeFiles/nstd.dir/ndebug.c.o: relocation illegal when not bound to object being created
0436 ---------------------------------------------------------------------
0437
0438 Thus at this time only GCC is supported for Solaris 10.
0439
0440
0441 == Building the code
0442
0443 ---------------------------------------------------------------------
0444 $ cd \$HOME/endurox
0445 $ make
0446 $ make install
0447 ---------------------------------------------------------------------
0448
0449 This will produce binaries in '\$HOME/endurox/dist' folder.
0450
0451 == Unit Testing
0452
0453 Enduro/X basically consists of two parts:
0454 . XATMI runtime;
0455 . UBF/FML buffer processing.
0456 Each of these two sub-systems have own units tests.
0457
0458 === UBF/FML Unit testing
0459
0460 ---------------------------------------------------------------------
0461 $ cd \$HOME/endurox/sampleconfig
0462 $ source setndrx
0463 $ cd \$HOME/endurox/ubftest
0464 $ ./ubfunit1 2>/dev/null
0465 Running "main" (76 tests)...
0466 Completed "ubf_basic_tests": 198 passes, 0 failures, 0 exceptions.
0467 Completed "ubf_Badd_tests": 225 passes, 0 failures, 0 exceptions.
0468 Completed "ubf_genbuf_tests": 334 passes, 0 failures, 0 exceptions.
0469 Completed "ubf_cfchg_tests": 2058 passes, 0 failures, 0 exceptions.
0470 Completed "ubf_cfget_tests": 2232 passes, 0 failures, 0 exceptions.
0471 Completed "ubf_fdel_tests": 2303 passes, 0 failures, 0 exceptions.
0472 Completed "ubf_expr_tests": 3106 passes, 0 failures, 0 exceptions.
0473 Completed "ubf_fnext_tests": 3184 passes, 0 failures, 0 exceptions.
0474 Completed "ubf_fproj_tests": 3548 passes, 0 failures, 0 exceptions.
0475 Completed "ubf_mem_tests": 4438 passes, 0 failures, 0 exceptions.
0476 Completed "ubf_fupdate_tests": 4613 passes, 0 failures, 0 exceptions.
0477 Completed "ubf_fconcat_tests": 4768 passes, 0 failures, 0 exceptions.
0478 Completed "ubf_find_tests": 5020 passes, 0 failures, 0 exceptions.
0479 Completed "ubf_get_tests": 5247 passes, 0 failures, 0 exceptions.
0480 Completed "ubf_print_tests": 5655 passes, 0 failures, 0 exceptions.
0481 Completed "ubf_macro_tests": 5666 passes, 0 failures, 0 exceptions.
0482 Completed "ubf_readwrite_tests": 5764 passes, 0 failures, 0 exceptions.
0483 Completed "ubf_mkfldhdr_tests": 5770 passes, 0 failures, 0 exceptions.
0484 Completed "main": 5770 passes, 0 failures, 0 exceptions.
0485
0486 ---------------------------------------------------------------------
0487
0488 === XATMI Unit testing
0489 ATMI testing might take some time. Also ensure that you have few Gigabytes of free
0490 disk space, as logging requires some space (about ~10 GB).
0491
0492 ---------------------------------------------------------------------
0493 $ cd \$HOME/endurox/atmitest
0494 $ nohup ./run.sh &
0495 $ tail -f \$HOME/endurox/atmitest/test.out
0496 ...
0497 ************ FINISHED TEST: [test028_tmq/run.sh] with 0 ************
0498 Completed "atmi_test_all": 28 passes, 0 failures, 0 exceptions.
0499 Completed "main": 28 passes, 0 failures, 0 exceptions.
0500 ---------------------------------------------------------------------
0501
0502 == Troubleshooting
0503
0504 This section lists some notes about fixing most common problems with Solaris build.
0505
0506 === Problems with library modes
0507
0508 If having issues with linking particular library version, for example building
0509 in 64bit mode, but for some reason CMake is linking with 32bit libs (for example
0510 with PostgreSQL), then following flag may be applied *CMAKE_LIBRARY_PATH* to
0511 point to correct path for libraries. For example:
0512
0513 ---------------------------------------------------------------------
0514 $ cmake -DCMAKE_INSTALL_PREFIX:PATH=`pwd`/dist -DDEFINE_DISABLEDOC=ON\
0515 -DENABLE_POSTGRES=ON -DCMAKE_LIBRARY_PATH=/opt/csw/lib/amd64 .
0516 ---------------------------------------------------------------------
0517
0518 == Conclusions
0519
0520 At finish you have a configured system which is read to process the transactions
0521 by Enduro/X runtime. It is possible to copy the binary version ('dist') folder
0522 to other same architecture machines and run it there without need of building.
0523
0524 :numbered!:
0525
0526 [bibliography]
0527 Additional documentation
0528 ------------------------
0529 This section lists additional related documents.
0530
0531 [bibliography]
0532 .Resources
0533 - [[[BINARY_INSTALL]]] See Enduro/X 'binary_install' manual.
0534
0535
0536 ////////////////////////////////////////////////////////////////
0537 The index is normally left completely empty, it's contents being
0538 generated automatically by the DocBook toolchain.
0539 ////////////////////////////////////////////////////////////////