There are 2 supported mechanisms for using the Geosoft GX API in an external application. The first (default) mechanism relies on an existing installation of Geosoft Desktop Applications being installed on the system. The second mechanism requires the installation and setup of a redistributable package. Each is described in a separate section below.

Redistribution Depending on a Geosoft Desktop Applications Instance

Applications that use this mechanism requires either Geosoft Viewer or Oasis montaj installed. A handful of thin wrapper dlls need to be placed next to your application binaries. These dlls take care of the redirection of API calls to the desktop platform where the functionality is implemented. The versioned redist dlls are available in the GeosoftInc/gxcore Github repository.

The API is serviced from the application via a number of small wrapper dlls. Under normal circumstances this is all that should be needed for the system to work. The default "Core" Geosoft registry keys (under HKEY_LOCAL_MACHINE\SOFTWARE\Geosoft) will be read to detect the location of the application binaries.  If not a geosoft.key text file can be placed next to the dlls. This file should contain a single line containing the alternative registry key. Usually this will be done to target a Geosoft Beta or Pre-Release instance. 

Beta and Pre-Release Testing

Beta and Pre-Release testing is only possible under the direction of Geosoft. 

If one wishes to execute code against the GX API with Beta or pre-release software it is usually necessary to redirect the wrapper dlls to the test installation. This can be achieved by placing a text file, geosoft.key, which contains a single line with the the name of the installation. For a released installation this will be "Core".  For a test system it will be "Core - Testing"; and for beta "Core - Beta". When your program runs we use the name in the geosoft.key file to identify the installation from the registry section HKEY_LOCAL_MACHINE\SOFTWARE\Geosoft. If the file is not present "Core" is assumed.

Standalone Redistribution

Standalone Redistribution requires no registry modification. It should also support a non-administrative per-user installation since it is fully self contained in a plain zip distribution. The redistributable zip files contain the necessary wrapper dlls in its root folder. The remaining binaries and other resources are available in a folder called GeosoftRedist. Once these files are placed next to the standalone binary that depends on it there are a number of additional steps to perform for it to work.

1. No geosoft.key file should be placed in the folder, only the wrapper dlls and the GeosoftRedist folder.
2. Inside the GeosoftRedist folder a text file called geosoft.redist needs to be created that contains 2 separate lines with writable folder paths. The first line should point to a location that can be used as the user folder for the instance and the second as the temporary folder.
3. When an external application initializes the GX API context with this system in place the following should occur:
   1. The wrapper dlls should discover the GeosoftRedist folder automatically. It will read the geosoft.redist file an obtain the 2 paths, creating them if they do not exist. If anything goes wrong during this step a UI error message is displayed and the process will display an error message box, then exit.
   2. The normal GX context initialization will occur, i.e.:
      
      1. A Geosoft Connect connection is established (installing Geosoft Connect automatically if not present) and a signed-in Geosoft ID is required in the same way as is true for our currently release GX API context initialization.
      2. The user folders and resources are created and refreshed in the same way as for Geosoft Desktop installations.

At this point any GX API that the signed-in Geosoft ID is entitled to via a Desktop Applications install should be available. There are two standalone redistributable packages available (9.5 release packages can be found here). 

1. Minimal - This contains a minimal set of binaries to support read and writing Geosoft formats, but also a large portion of the core algorithms (depending on entitlement) etc. This distribution does not contain any third-party format support, GX binaries or any UI mechanisms.
2. Full - This is basically a full Oasis montaj package (except for anything that requires the 32-bit interop layer like ER Mapper, ArcGIS ArcEngine etc.). Even the montaj application binaries can be found and run (subject to Geosoft ID entitlement) from the bin directory. There are methods in the gxpy Python APIs that use these as document viewers.

Standalone Use via GXPY

In version 9.5 the gxpy Python setup.py mechanism has been modified to automate the configuration of a local Python environment to use one of the standalone redistributable packages instead of a Geosoft Desktop Applications instance. To do this follow the following steps:

1. Download a release or checkout a branch from https://github.com/GeosoftInc/gxpy 
2. Choose which standalone package you need, Full vs Minimal, and simply place (no need to extract the zip file locally (e.g. C:\GXDownloads).The Full package is necessary for all the gxpy tests and other examples to work.
3. To install the module and extract and setup the redistributable files run the following within your Python environment (the location of the user and temp directories can be anything, but needs to exist and be writable):
   • python setup.py install --standalone_dist=C:\GXDownloads\RELEASE_9.5.0_55_redist_full.zip --standalone_temp=C:\Users\MyUser\AppData\Local\Geosoft\MyPython\temp --standalone_user=C:\Users\MyUser\AppData\Local\Geosoft\MyPython\user
   • It is also possible to subsitute develop for install in the command above to use the extracted gxpy files in place, rather than install them into the Python environment. This is useful for development purposes within gxpy.