CXFORM installation instructions ============================ REQUIREMENTS ============================ A C compiler is required to build CXFORM unless a prebuilt binary is available for your platform. The GCC compiler is strongly recommended for building the library on *NIX platforms, as other compilers have not been tested and may be incompatible. It is freely available from: http://gcc.gnu.org/ If compiling under Microsoft Windows, the solution is not as straightforward. If you do not plan to use CXFORM with IDL, the Cygwin environment (which contains GCC) is recommended and free (http://www.cygwin.com/). However, since IDL 6.0+ under Windows has been compiled with Microsoft Visual C++ 7.0, it requires a compatible compiler. Namely, itself, or Microsoft Visual C++ Toolkit 2003, which is free. If you do not care about building the files yourself, hopefully you will find precompiled binaries for your specific platform on the CXFORM web page. ============================ BUILDING and INSTALLING ============================ * Windows XP/2000 instructions + Building for IDL (and C) - Extract the contents of the CXFORM download to a place of your choosing - Build the DLL/DLM (skip this step if you are using prebuilt files) - As stated in the REQUIREMENTS, you must have a compiler that is compatible with Microsoft Visual C++ 7.0 installed. - Open the "make_CXFORM_MSVC.bat" file in a text editor. - Change the "SET IDL_DIR=c:\dev\RSI\idl63" path to reflect the location of your IDL installation - Run the "make_CXFORM_MSVC.bat" file from a command prompt. This should build a file named "cxform.dll" * NOTE: In versions of IDL earlier than 6.3, you may need to change a line in the Makefile to use "idl32.lib" instead of "idl.lib" - IDL requires that "cxform.dll" and "cxform.dlm" live together in the same directory, which must be one of: 1) the current directory (".") 2) IDL's binary directory ("$IDL_DIR/bin/bin.") 3) a directory pointed to by the IDL_DLM_PATH environment variable For testing purposes, option (1) is fine. For production, though, you want IDL to see them no matter where you're cd'ed to, and option (3) is the cleanest. Refer to the following instructions: Right-click on My Computer and go to Properties. Click the Advanced tab, and then push the "Environment Variables..." button. Under the top section, "User variables for username", click the "New..." button. Enter "IDL_DLM_PATH" for the Variable Name. The path to cxform.dll and cxform.dlm should be entered in the "Variable Value" field. In this case it would be, "C:\dev\projects\cxform". (Neither of the entries should have quotes) "OK"-click your way out of the dialog boxes and you should be ready to use CXFORM under IDL. + Building for C (no IDL access) - You may choose to build for C with either Cygwin/GCC or Microsoft Visual C++ 7.0 (or MSVC++ Toolkit 2003). - Cygwin/GCC: - Type "make dll-c" at the command prompt. This should build a file named "cxform-c.dll" - MSVC++: - Type "make_CXFORM_MSVC.bat" at the command prompt. This should build a file named "cxform-c.dll"; that is, unless your paths are set correctly for IDL. If so, it will build "cxform.dll", which is a superset of "cxform-c.dll". - Include the "cxform.h" file in your C source code. Call the CXFORM function according to the prototype in that header file. - Link to the CXFORM dll file when building. An example of how to do this can be found in the Makefile (gcc) or make_CXFORM_MSVC.bat when it builds "main.exe". * Linux/SunOS/Mac OS X/*NIX instructions + Building for IDL (and C) - Create the shared library for IDL - Type "make so" at the command prompt. This should build a file named "cxform.so" - IDL requires that this file and "cxform.dlm" live together in the same directory, which must be one of: 1) the current directory (".") 2) IDL's binary directory ("$IDL_DIR/bin/bin.") 3) a directory pointed to by $IDL_DLM_PATH For testing purposes, option (1) is fine. For production, though, you want IDL to see them no matter where you're cd'ed to, and option (3) is the cleanest. Refer to the following instructions. If you have IDL 5.3 or greater, the solution is simple and elegant: just copy the files (cxform.so and cxform.dlm) to a local architecture-specific directory (for example, "/usr/local/lib/idl"), then add a line to your .cshrc (or your shell-specific preference file): setenv IDL_DLM_PATH "/usr/local/lib/idl:" Note that for the Bash shell, you would use the following line instead: export IDL_DLM_PATH="/usr/local/lib/idl:" Be careful: the angle brackets are mandatory, since that's the convention defined by RSI. This then makes the quotes mandatory, too, to prevent the shell from treating the angle brackets as I/O redirection). NOTE: If compiling under SunOS and your default compiler is not gcc, you mayneed to add the following line to the Makefile: CC=gcc + Building for C (no IDL access) - Create the shared library for C - Type "make so-c" at the command prompt. This should build a file named "cxform-c.so" - Include the "cxform.h" file in your C source code. Call the CXFORM function according to the prototype in that header file. - Link to the "cxform-c.so" library when building. - Move "cxform-c.so" into a folder somewhere in your LD_LIBRARY_PATH. To view what directories are in this path, type "env" and look for the "LD_LIBRARY_PATH" value. If you do not wish to copy the .so file into one of those directories (or do not have permission), copy the .so file into a directory of your choosing and add it to the "LD_LIBRARY_PATH" value in your .cshrc (or appropriate shell) file. An example of usage can be seen in the included main.c file, which can be built by typing "make main". Note that if you modify the main.c file, you will need to perform a "make clean" then "make main", as the Makefile is set up for multiple platforms and redirections and does not correctly detect changes in the source code. NOTE: If compiling under SunOS and your default compiler is not gcc, you may need to add the following line to the Makefile: CC=gcc ============================ TESTING ============================ Start IDL, then type "help, 'cxform', /dlm". You should see something like: IDL> help,'cxform',/dlm ** CXFORM - Ed Santiago's Coordinate Transform package (not loaded) Version: 0.2, Build Date: 2000-06-14 12:00, Source: esm@lanl.gov Path: /path/to/wherever/you/installed/it/cxform.so IDL> (If you see '% Unknown dynamically loadable module: cxform' instead, please ) (go back to the installation sequence and make sure your IDL_DLM_PATH is ) (set properly, and the files cxform.so and cxform.dlm are in proper place.) Now try something that will force the library to be loaded. Type: IDL> print, cxform() % Loaded DLM: CXFORM. % Usage: v_out = CXFORM( v_in[3], `from', `to', et ) % Execution halted at: $MAIN$ IDL> If it makes it this far, you're all set. If it bombs out, it's possible that the .dll or .so file wasn't built properly, the compiler is different than the one used to build IDL (try typing print, !MAKE_DLL.COMPILER_NAME), or the binary is for the wrong architecture. ============================ USING IT ============================ See readme.txt for an introduction to using the package. ============================ ============================ If there are problems with your build/install, please contact me at Ryan.A.Boller@nasa.gov