############################################################################## # Modular IMP - README ############################################################################## Modular IMP, or Waiting for PIXY, or simply JLib 3.0 Once upon a time back in the year 2000 I started to distribute some small functions I had written for IMP. This grew to be know as the J-Library, or JLib for short. Now, three years later and my presence no longer certain in the house, I am trying to allow any user to write their own modules to distribute in the house in a similar manner. Ok, I (still) know this is the way (and much better too) the new and lovely PIXY is working. But, alas, some things are still lacking in PIXY. I myself is e.g. in the need of feature handling, which has not yet stabilized in the PIXY code. So, while waiting, I did my own solution. So, if you like to try, start by making a *BACKUP COPY* of your Imp. OBS! This procedure should be followed both by existing JLib 2.0 users and by those of you who have not used JLib before. If you do *not* have your personal Imp, I suggest that you either a) read Petters startkit instructions on how to create your own personalized imp version. You can find his readme file here: /usr/users/programbas/petter/imp/startkit/README (You may want to compile his startkit first, to check that it went alright before installing JLib.) or b) just go on, and I will create a minimal imp for you. It is important that you run the install script in the directory where you keep and also in the future intend to keep your IMP-source. So do not copy your source files to the directory "strange_name" and run things from there. Note: It is recommended that you read through the whole of this document before starting the installation, so you know what is going on. ... Finished with the backup? Ok, let's go then! #################################################################### QUICK INSTALLATION: Cd to your current IMP-source directory. (If you don't have any, just make a directory where you want your IMP to be, e.g. mkdir ~/myimp; cd ~/myimp) Issue the following commands: If you are sitting at CBA: $ /usr/users/joakim/imp/public/jlib3/bin/jlib_install or if you have just completed a working JLib install on your Linux machine (see below): $ $JLIB_HOME/bin/jlib_install Read the output and check that it looks ok (you may have to manually edit your login files). Logout and login again (or issue: source ~/login) $ make world $ myimp ... that's all! (make world is he same as: make clean && make depend && make all) Now, you hopefully have a menu in IMP called J-Lib Try the last function: About JLib and check that it prints out some info in a message box and in your terminal window. If you get some error messages, see the TROUBLE section below. It may be a good thing to logout and login again, to check that the Environment variables are still correct. Try uncommenting the line IMP_MODULES+=${JLIB_HOME}/example_module in the file "impsettings" to test adding another module. You must run make to get your changes in impsetting to be used. #################################################################### LINUX INSTALLATION: Easiest if you first make a global jlib install, see separate file puh.cb.uu.se:/usr/users/joakim/imp/public/distro/README then proceed with the install as described above. #################################################################### IMPORTANT FACTS AND CHANGES TO THE MAKE SYSTEM: Some things have changed. Do read this section so you know what is going on. *** The myimp script To start imp from now on, you should run the myimp script. This sets all environment variables the way they should be and runs your imp from any directory. There is no need to start imp from your imp directory any more. The myimp script resides on my account, in case anything needs to be changed to it. See the PATH section below. You can of course set this to suit your own taste. *** You have a new file impsettings This is where you tell make what files to compile *and* which modules to include. This replaces your old myfiles if you are a JLib 2.0 user. *** You have a new sub directory (link) in your imp directory called jlib This is where all my source files are. This is just for you to easier find jlib files. It is optional to have JLib as a module, and you can remove it if you like. For JLib functionality, see separate README in the JLib directory. *** JLib 2.0 users only! mywhipfuncs.h is now named ownwhipfuncs.h Back to the usual way of writing things. *** impmain.c replaces whipown.c, widown.c and wifownenum.c Do remove the old files if you have not added any additional code into them. Yes, enums are supported. See the example_module. *** There is still no support for multiuser feature definitions :-( I have written some features (see jlib/jfeatures.cc and jlib/jlib.featop) but they may collide with features you have written yourself. If this happens, your features will win, and you will get an error message when starting imp, that it cannot read jlib.featop like this one: --Warning, failed to read (at least part of) /usr/users/joakim/imp/jlib/jlib.featop If you want my features to work together with your features, talk to me and we can hopefully work it out together. *** There are some new environment variables I have made some changes to your ~/.login and ~/.bash_profile files. This is to automatically set the following variables: MYIMP: This points to your imp-directory JLIB_HOME: This points to the location of JLib CC and CXX: This is your default c and c++ compiler, I have set this to be cc and cxx (on the alpha machines) as it is faster than g++. See the CHANGING COMPILER section below. *** IMP is no longer in your home directory The IMP file which contains menu definitions is now read from $MYIMP/IMP *** What about the Makefile? Now called GNUmakefile The makefile has changed A LOT, and I am not perfectly sure that it will not change more over time. Therefore I install it as a link to a central makefile, so that I can change in one place to affect all. Of course you can copy the GNUmakefile to your own directory if you wish to change it. The makefile requires GNU-make (gmake), and will give an error message if you try to us another make. See the TROUBLE section. Your old Makefile is stored under the name Makefile.before_jlib3 and can be removed. *** How to tell make about my source files? This is done in a file called "impsettings" in your source directory. It should contains one line like this: SRCSOWN = file1.c file2.c file3.cc file4.cpp It works with extensions .c, .cc, .cpp, .cxx and .C Whenever you add a new c/c++ file to imp, you should add it to your "impsettings" file. *** What about this thing with modules then The "impsettings" file, may also contain a list of modules that you wish to include when using your imp. I preset inclusion of JLib e.g. Read comments in "impsettings" for more information about this. See the $JLIB_HOME/example_module directory to get an example on how to write your own module. It is very easy. *** Object files? As I personally hate to have a lot of .o files among my .c files, I have arranged so that the makefile puts them in a separate directory called obj_alpha_cxx (or similar). No need to look at them any more, no need to touch, just forget. *** IMP-Macros? Macros can also reside in multiple directories. JLib macros you can find in jlib/macros/. You can move your own macros to $MYIMP/macros/ if you like (to improve the structure of your sources). *** Different architectures As I am working on an Intel machine, which has a different binary format than the Alpha machines of the rest of you. It should be easy to switch between architectures. That is the reason for the _alpha_ in very many names. It is put there automagically by the make system. Compile on my machine, and you will get _i686_ instead. Simple and works fine. *** Different compilers It is always a good thing to test your code on different compilers to make sure you follow standard, and some produces better error messages than others etc. The make system separates different compilers just in the same way as different architectures. This is selected with the environment variable CXX. The CC variable will be set to follow CXX (cc for cxx and gcc for g++). If you wish to compile for g++ instead of cxx just set CXX=g++. Note that the myimp script also uses the CXX variable to select the binary to run. This way you can have two ready compiled versions of imp, one cxx and one g++ version. The myimp script prints the name of the executable it runs. OBS! I haven't managed to get the dynamic linking to work correctly with gcc/g++ on the alpha system at CBA. I don't know why. All help appreciated. *** Make options clean = remove object files distclean = clean + remove the imp executable cleanall = clean for all architectures and compilers distcleanall = distclean for all architectures and compilers depclean = make clean also in dependent module directories depend = establish dependencies all (default) = normal compile link = relink only (I've found this very useful) world = clean + depend + all (I.e. remake all from scratch) help = print some make options lint = run lint checking program (only useful for c-code) verbose = print names of all source files, all object files and the output file #################################################################### TROUBLE *** "This makefile requires Gnu make (gmake)" If you cannot compile, and get this message, then you are not running the GNU-make. This resides in /usr/local/bin on the Alpha system. If you don't want to set the path to point at /usr/local/bin before /usr/bin (OBS! This messes up man pages!), then you can write gmake instead of make. Convenient is to issue alias make gmake. *** "--Warning, failed to read (at least part of) .../jlib.featop" This is because you have defined your own features, which take precedence over the features of JLib. If you want the JLib features to function together with your features, talk to me and we can hopefully work it out. *** If everything fails Well, I guess you know where I am sitting ;-) #################################################################### RUNNING OTHER PEOPLES IMP:s The need for this should of course be reduced with the new modularity. However it is still possible and quite simple. Just set the MYIMP variable to point at some other persons imp-directory and run myimp as usual. This requires that both you and the other person have installed JLib. #################################################################### DOCUMENTATION OF THE JLIB-FUNCTIONS See the jlib/README file #################################################################### CONTRIBUTIONS TO THE COMMUNITY Now you can spread your own functions without too much trouble, so please do! If you have ideas how to improve things, just come and talk to me. #################################################################### Ok, that's all folks. Hope you like it. Please let me know what you think. Cheers! /Joakim Lindblad Last edit: 2003-06-19