Alpha_1 Programmers's Manual

Alpha1 Shared Library Support

Shared libraries are now available on the sgi's and sun sparc's. They should become available on the hp800's shortly (after Greg leaves). The addition of shared libraries should greatly aid the development of new Alpha 1 code. The main reason for this being true is that compile times will drop from over 5 minutes, in some cases, to mere seconds. It is also now possible to compile only the code you are changing (or adding) and not have to recompile the executable. This is possible due to dynamic run-time loading. All of this comes with only a little time and effort to change the current practices. It is worth it - really.


Setup

In order to use the shared libraries you must first make sure that your environment is setup properly. A few new environment variables and directories are needed to make the whole process easier and faster. Please read this section carefully or run-time results could be a lot less than intuitive.

LD_LIBRARY_PATH

Shared libraries are loaded at run-time. This can not be done if the run-time loader (rld) can't find the libraries. The rld uses the LD_LIBRARY_PATH variable to search for the shared libraries. Changes to the set-envars program now record the LD_LIBRARY_PATH in the environment variable ORIG_SL_PATH. For this reason do NOT change the LD_LIBRARY_PATH after this script has run. Some of the older Alpha 1 setup files do make changes after set-envars has been called - check this. If you do change LD_LIBRARY_PATH, then you risk either losing the use of Alpha 1 libraries or having your additions lost without warnings. If you must tinker with the LD_LIBRARY_PATH do so prior to calling set-envars in your .customs.cshrc file.

Directories

To make rld's job easier (as well as your own) it is best to have the libraries in as few places as possible. For this reason libraries compiled in the working tree are no longer left in the library source directory. Instead, they are moved to $w$wlib. This variable is set to point to $A1WRK/lib/$A1MCH. This allows you to work on more than one architecture without your libraries co-mingling.

To make the directories needed for creating and using the shared libraries in your working tree, cut the following lines and paste them at your UNIX prompt. Do this for each of your working trees. You may of course create only the machine directory you will be using but it is recommended to have them all. 

	cd $w
	md lib
	cd lib
	md aindy
	md asparc
	md ahpux800
	md adecmips
	md asun4
Warning: You must keep these directories clean. Since the selection of libraries is now done at run-time and not by uncommenting a line in the makefile, you must keep only the libraries you are working on in $w$wlib. For instance, say you work on clientlib for a while, get it working, check in your work but then leave the library laying in $w$wlib. Later someone else adds some new incredible features to clientlib and checks them in. You start working on ogldllib and can't seem to get any of the new features to show up. They won't. This is because you left an old version of clientlib in $w$wlib that is being used along with the ogldllib you were wanting to test. You can not selectively load libraries from your working trees so keep this directory clean.


Scripts

A few new scripts are provided to allow you to select where the libraries used by Alpha 1 programs will be found. The default setup at login is for all of the libraries to be loaded from A1BIN. If you want to run these programs with the debug information you would simple type usea1dbg and re-run the executable. Notice that no compiling was necessary. These scripts (actually aliases that run a script with various parameters) manipulate the LD_LIBRARY_PATH. If you change working trees you must run the script again so that the current working tree is used. Also, be sure that if you do switch working trees that you change A1WRK and w. 

 usea1bin
Use A1BIN only. This script does not use any debug information and also does not bring in any libraries from the working tree. 
 usea1dbg
Use A1DBG only. This script uses the debug libraries from the Alpha 1 tree but does not use any working tree libraries. 
 usewrkbin
Use WLIB then A1BIN. This script allows you to use your working tree libraries with the Alpha 1 optimized libraries. This will make it possible for you to have debug information in your working tree libraries but not in the Alpha 1 libraries. 
 usewrkdbg
Use WLIB then A1DBG. This script allows you to use your working tree libraries with the Alpha 1 debug libraries.


Sample Session

What follows is a simple example of how to use the system now that shared libraries are among us. Since some machines do not have shared library support yet a sample session is given for those who may be using one of those machines.

The scenario is as follows. You are editing motif3d to do some clever surface tracing using the third mouse button. To keep things simple, you make all of your changes within the file drawing_area.C which of course is part of clientlib. You don't care (or don't know how) to use dbx or gdb so you decide to used optimized object files.

Using shared

Using the shared libraries should save you considerable time. First of all remember that you do NOT have to recompile motif3d in your working tree. You do not even have to go to that directory at all if you don't want to. Simply follow these 6 steps:

  1. type usewrkbin
  2. uncomment OPTIMIZED_OBJECTS in the $w$clientlib makefile
  3. edit drawing_area.C in $w$clientlib
  4. type a1make in $w$clientlib
  5. type motif3d
  6. goto step 3 until you are finished
Step 1 uses the dynamic loading script to make the rld look first into your working tree and then into the binary library of Alpha 1.
Step 2 forces a1make to use the optimized objects and not the debug versions (speeding up your compile - clever).
Step 3 is where you make your changes in your working copy of drawing_area.C that you checked out using CVS.
Step 4 makes the library libClient.so and moves it into $w$wlib. Recall that in step 1 we told rld to look there for our work. If you didn't read the warning above do so.
Step 5 runs the motif3d that resides in the Alpha 1 tree. You did not have to make your own copy or recompile!
Step 6 is where you see you made a mistake and you go back to fix it...

Not using shared

This section should only be relevant for users sitting behind machines that do not support shared libraries. If you are on a machine that does support shared libraries then you have to use them so read the above section. The process has not changed much for these machines from the old days.

  1. uncomment OPTIMIZED_OBJECTS in the $w$motif3dd makefile
  2. add $w$clientlib/*.o to NEW_OS in the $w$motif3dd makefile
  3. edit drawing_area.C in $w$clientlib
  4. type a1make objs in $w$clientlib
  5. type a1make motif3d in $w$motif3dd
  6. type ./motif3d
  7. goto step 3 until you are finished
Step 1 forces a1make to use optimized objects when making motif3d.
Step 2 allows you to include your work in the executable. This is a change that takes the place of uncommenting a line that started with LClient. See Advanced Options below.
Step 3 is where you make your changes in your working copy of drawing_area.C that you checked out using CVS.
Step 4 makes drawing_area.o in $w$clientlib.
Step 5 makes motif3d in $w$motif3dd. This is the time consuming step that is pruned by using shared libraries.
Step 6 runs the local copy of motif3d. Notice that you must use the "./" in order to use your version.
Step 7 is where you curse out loud when you relized you made a mistake that is going to force you to compile everything again.

Advanced Options

These options are not Advanced in the sense that they are difficult to use. They are simply listed as advanced because you normally would not use them but they may cut down compile time in some instances.

OPTIMIZED_OBJECTS

You saw this in use in the sample session. If this variable is left commented out the debug object files will be used in building the library. Debug objects tend to be much larger and therefore slow down compilation. It is probably your best bet to uncomment this variable. You still will have debug information on the files you changed just not on the ones you did not. However, if you want debug information for the whole library comment this variable out.

OPTIMIZED_LIBRARIES

This is a hold over of the previous system. By uncommenting this variable optimized libraries (ones without debug information) will be used instead of the debug libraries. This option is only available when compiling an executable and therefore should not come into play very often. However, if for some reason you are compiling an executable (for instance the library takes longer to compile that the executable does) then this option is very useful.

NEW_OS

This is a new option. Previously one would uncomment a line of code in the makefile that would tell a1make to use their object files and then the library. Under this system those lines have been eliminated (for one reason they were incredibly painful to maintain as the system changed). There now is one variable, NEW_OS, that you simple place a list of objects after that you want to use. For example, say you wanted to use your own command interpreter in tk3d. You could add the file to libTCL but you decide to just recompile a1wish with your object file included. This would be accomplished by changing
	NEW_OS  =
into 
	NEW_OS  = $w$tcllib/*.o
in the a1wish makefile. More than one object can be included as well by simply listing them one after the other. An example would be
	NEW_OS  = $w$tcllib/*.o $w$x11dllib/*.o junker.o 	\
		  /home/grad/fred/test_stuff/tcp_ip.o $w$trimlib/*.o
Once again, please note that this should only be used if it takes longer to make the library than it does to make the executable or if the new object files are simply not part of any library. Another note of importance, if you don't change the files that contribute to NEW_OS then you still don't have to recompile the executable. Keep these things in mind and you will save yourself a LOT of time.

Library Override

If you find it necessary to build an executable (which would be necessary if you change the interface of a library that the executable uses - add a new function that is visible externally or change a class for example) then you are still in luck. Previously you would need to uncomment different sections of the makefile in order for the compiler to use your work. This is now done automatically. If you have a library in $w$wlib that your executable needs then it will automatically be chosen over the one in the Alpha 1 binary (or debug) tree.

This does; however, bring up a new possibility that once before did not exist. Since this is happening without your requesting it, it is bound to happen at some point that do not want it to. If you are getting odd results check your compile line to see if the libraries being used are the ones you expected. If something was pulled from your $w$wlib it will be rather obvious in the link line.

Note: Just because it compiles against your working tree version doesn't mean it will use it at run-time. You still must use either usewrkbin or usewrkdbg to make the run-time loader choose your library. This becomes very important if the interfaces to the two libraries differ. The one used at run-time must have the same interface as the one compiled against.


Alpha_1 Programmer's Manual Home Page
Alpha_1 Programmer's Manual. Version 95.06.
Copyright © 1995, University of Utah
alpha1@gr.utah.edu