5. Compiling and Linking
This chapter describes how to compile and link your C/C++ applications and user actions.
The focus is directly on operations for each compiling or linking alternative on each GemStone platform. It is assumed that you already know which alternatives you want to use, and why, and when. Those topics are part of the application design and code implementation, which are described in other chapters of this manual.
All operations are illustrated as though you are issuing commands at a command-line prompt. You may choose to take advantage of your system’s programming aids, such as the UNIX make utility and predefined environment variables, to simplify compilation and linking. Whatever you choose, be sure that you designate options and operations that are equivalent to those shown here.
NOTE
Much of the material in this chapter is system-specific and, therefore, subject to change by compiler vendors and hardware manufacturers. Please check your GemStone/S 64 Bit Release Notes, Installation Guide, and vendor publications for possible updates.
5.1 Development Environment and Standard Libraries
Set the GEMSTONE environment variable to your GemStone installation directory; the command lines shown in this chapter assume that this has been done. No other environment variables are required to find the GemStone C++ libraries.
GemStone requires linking with certain architecture-specific “standard” C and C++ libraries on some platforms. The order in which these libraries are specified can be significant; be sure to retain the ordering given in the example command lines.
The environment of the supported Unix platforms is System V. On these platforms, the /usr/bin directory should be present in the PATH environment variable. If /usr/ucb is also present in PATH, then it should come after /usr/bin. The System V “standard” C/C++ libraries (not Berkeley) should be used in linking.
5.2 Compiling and Linking C Source Code for GemStone
The following information includes the requirements and recommendations for compiling C applications or user actions for GemStone. Your C code may have additional requirements, such as compile options or environment variables.
Compiling
The C++ Compiler
C applications and user actions must be compiled and linked with a compiler that is compatible with GemStone libraries and object code. This chapter assumes that a compatible compiler has been installed and is in your path.
The C++ compilers listed in section Platform Specific versions and example options were used to produce the GemStone product, and have been tested for producing C/C++ applications and user action libraries. Other compilers, such as ANSI C++ compilers, are assumed to work, but have not been tested.
Compilation Options
Compiling user actions and GCI applications use the same compilation options.
When you compile, specify each directory that is to be searched for include files separately by repeating the -I option. At a minimum, you must specify the GemStone include directory, but it is likely you will have other include file directories.
For simplicity in compiling code for user actions, the .c file is assumed to be a library containing both the source code for one set of user actions and the implementation of the function that installs them all with GemStone.
The -c option inhibits the “load and go” operation, so compilation ends when the compiler has produced an object file.
If you have multiple application or user action files, they should all be compiled under these same basic conditions.
For more information and details on the complier options and other compiler flags, please consult your compiler documentation.
Linking
Use the same C++ compiler to link your GemStone C/C++ code as you use to compile it.
Link options
Linking user actions and GCI applications require different link options.
There is no difference in the link options for applications that will login linked or RPC. The run-time binding is done by code that is part of the application. The same application can use either the RPC or linked GemBuilder libraries with this type of binding.
Linking with shared libraries does not require that all entry points be resolved at link time. Those that are outside of each shared library await resolution until application execution time, or even until function invocation time.
NOTE
When you link a user action shared library, be aware of the dangers of incorrect unresolved external references. If you misspell a function call, you may not find out about it until run-time, when your process dies with an unresolved external reference error. Be sure to check your link program’s output carefully.
The -o option designates the path of the executable file produced by the link operation.
Be sure to employ at the appropriate times the link option that designates symbolic debugging (often -g).
For information on most options, please consult your linker documentation.
If you have multiple application or user action files, they should all be linked under the same basic conditions.
Risk of Database Corruption
CAUTION
Debug your C/C++ code in a process that does not include a Gem.
Do not log into GemStone in a linked application or run a Gem with your user actions until your C/C++ code has been properly debugged.
When your C/C++ code executes in the same process as a Gem, it shares the same address space as the GemStone database buffers and object caches that are part of the Gem. If that C code has not yet been debugged, there is a danger that it might use a C pointer erroneously. Such an error could overwrite the Gem code or its data, with unpredictable and disastrous results. It is conceivable that such corruption of the Gem could lead it to perform undesired GemStone operations that might then leave your database irretrievably corrupt. The only remedy then is to restore the database from a backup.
There are three circumstances under which this risk arises:
- You are running your linked application and you have logged into GemStone.
- You are running any linked application and you are executing one of your user actions from the application.
- You are running any Gem, even a remote Gem, and you are executing one of your user actions from the Gem.
To avoid the risk, you must run your C code in some process that does not include a Gem. If the Gem is in a separate process, it has a separate address space that your C code should not be able to access. Use the RPC version of an application, and run any user actions from the application.
5.3 Platform Specific versions and example options
The compile command lines for each platform illustrate how to compile a simple application program or user action file named userCode, whose source contains one code file, userCode.c. Its result is one object file, userCode.o.
For simplicity in compiling code for user actions, this file is assumed to be a library containing both the source code for one set of user actions and the implementation of the function that installs them all with GemStone.
The link command lines illustrate
- how to link a user action object file named userCode.o with GemStone libraries to produce a user action library named libuserAct.so or libuserAct.dylib, depending on your platform.
- how to link a simple application program with one application object file, userCode.o. Its result is one executable file, userAppl.
Use the same C++ compiler to link your GemStone C/C++ code as you used to compile it.
Linux Compile and Link Information
Complier version
Red Hat Linux ES 8.1: gcc/g++ 8.3.1
Red Hat Linux ES 7.x: gcc/g++ 4.8.5
Ubuntu 20.04 LTS: gcc/g++ 9.3.0
Compiling a user action or GCI application
g++ -fmessage-length=0 -fcheck-new -O3 -ggdb -m64 -pipe
-D_REENTRANT -D_GNU_SOURCE -pthread -fPIC -fno-strict-aliasing
-fno-exceptions -I$GEMSTONE/include -x c++ -c userCode.c
-o userCode.o
The following warn flags are recommended for compilation:
-Wformat -Wtrigraphs -Wcomment -Wtrigraphs
-Wno-aggregate-return -Wswitch -Wshadow -Wunused-value
-Wunused-variable -Wunused-label -Wno-unused-function
-Wchar-subscripts -Wmissing-braces -Wmissing-declarations
-Wmultichar -Wparentheses -Wsign-compare -Wsign-promo
-Wwrite-strings -Wreturn-type -Wno-format-truncation
-Wuninitialized
If you want to stop the compilation process when any of the above warnings are encountered, use the following flag:
-Werror
To allow debugging of the resulting library, also include the optional -g
flag and omit the optimization flag -O3.
Solaris on x86 Compile and Link Information
Compiling a user action or GCI application
CC -xO4 -m64 -xarch=generic -Kpic -mt -D_REENTRANT
-D_POSIX_PTHREAD_SEMANTICS -I$GEMSTONE/include
-features=no%except -c userCode.c -o userCode.o
To allow debugging of the resulting library, include the optional -g flag and omit the optimization flag -xO4.
AIX Compile and Link Information
Compiling a user action or GCI application
xlC_r -O3 -qstrict -qalias=noansi -q64 -+ -qpic
-qthreaded -qarch=pwr6 -qtune=balanced -D_LARGEFILE64_SOURCE
-DFLG_AIX_VERSION=version -D_REENTRANT -D_THREAD_SAFE
-qminimaltoc -qlist=offset -qmaxmem=-1 -qsuppress=1500-010:1500
-029:1540-1103:1540-2907:1540-0804:1540-1281:1540-1090:1540-2988
-qnoeh -I$GEMSTONE/include -c userCode.c -o userCode.o
Depending on your version of AIX, you need to include -DFLG_AIX_VERSION=71 or -DFLG_AIX_VERSION=72.
Also note that there is no space in the -qsuppress arguments that are continued on the following line.
To allow debugging of the resulting library, also include the optional -g,
-qdbxextra and -qfullpath flags, and omit the optimization flag -O3.
DARWIN Compile and Link Information
Compiling a user action or GCI application
g++ -fmessage-length=0 -O3 -ggdb -m64 -pipe -fPIC
-fno-strict-aliasing -D_LARGEFILE64_SOURCE -D_XOPEN_SOURCE
-D_REENTRANT -D_GNU_SOURCE -I$GEMSTONE/include -x c++
-c userCode.c -o userCode.o
The following warn flags are recommended for compilation:
-Wno-format -Wtrigraphs -Wcomment -Wsystem-headers -Wtrigraphs
-Wno-aggregate-return -Wswitch -Wshadow -Wunused-value
-Wunused-variable -Wunused-label -Wno-unused-function
-Wchar-subscripts -Wno-conversion -Wmissing-braces -Wmultichar
-Wparentheses -Wsign-compare -Wsign-promo -Wwrite-strings
-Wreturn-type -Wno-nullability-completeness
-Wno-expansion-to-defined
To allow debugging of the resulting library, also include the optional -g
flag and omit the optimization flag -O3.
Windows Compile and Link Information
GemStone/S 64 Bit supports Windows only as a client platform. You may compile and link GCI applications, but not user actions, on Windows.
Compiling a GCI application
cl /W3 /Zi /MD /O2 /Oy- -DNDEBUG /TP /nologo /D_LP64 /D_AMD64_
/D_CONSOLE /D_DLL /DWIN32_LEAN_AND_MEAN /D_CRT_SECURE_NO_WARNINGS /EHsc
/DNATIVE /I 'VisualStudioInstallPath\atlmfc\include'
/I 'VisualStudioInstallPath\VC\include'
/I 'C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Include'
/I '%GEMSTONE%\include' -c userCode.c -FouserCode.obj
Linking a GCI application
link /LIBPATH:"VisualStudioInstallPath\VC\lib\amd64"
/LIBPATH:"C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Lib\x64" -RELEASE
/OPT:REF /INCREMENTAL:NO /MAP /nologo /MANIFEST
/MANIFESTFILE:userAppl.exe.manifest
/MANIFESTUAC:"level='asInvoker'" userCode.obj
%GEMSTONE%\lib\gcirpc.lib ws2_32.lib netapi32.lib advapi32.lib
comdlg32.lib user32.lib gdi32.lib kernel32.lib winspool.lib Secur32.lib /out:userAppl.exe