Back to home page

Enduro/X

 
 

    


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 ////////////////////////////////////////////////////////////////