GridFlow 0.7.6 -

Software (and Hardware) you Probably Need

Required Hardware (One of...):

• 1 : i386 : "old" PC, or "new" PC with old compiler
• 2 : i686 : "new" PC with recent compiler (that's the one we mostly test with)
• 3 : ppc : Macintosh (we are beginning to test with this too)
• 4 : armv4l : Corel Netwinder (unsupported, but got it to work long ago)
• 5 : mips : Silicon Graphics, non-PC (unsupported, but got it to work long ago)
• 6 : sparc : Sun SparcStation (unsupported, but got it to work some time ago)

Required Software:

• 1 : Ruby 1.6.6 or more recent (1.8.0 recommended)
• 2 : GNU C Compiler (gcc)
• 3 : GNU Make (gmake)

Very Recommended:

• 1 : X11 Display Server and MIT-Xlib (already in linux)
• 2 : one of:
  • 1 : jMax 2.5
  • 2 : jMax 4.1
  • 3 : PureData

Optional:

• 1 : PureData 0.35 or 0.36 (support is experimental)
• 2 : Simple Directmedia Layer (sdl)
• 3 : Ascii Art Library (aalib)
• 4 : HeroineWarrior's libmpeg3.so
• 5 : HeroineWarrior's libquicktime.so
• 6 : Greg Ward's libmpeg.so ("Berkeley/MNI")
• 7 : a digitizer card with a Video4linux 1.x driver (videodev.h)
• 8 : Ruby add-on "xmlparser" (for editing documentation)

NOTE: for help on installing and compiling jMax, please see Christian Klippel's extensive help file at nil as well as the jMax docs.

Also Useful:

• 1 : Pentium-compatible CPU (for profiling)
• 2 : CVS (for live update)

NOTE: There are several different incompatible libmpeg's from different authors; I found four of them, some numbered 2 and 3 as if they were version numbers (but it seems they are not).

NOTE: if one of your libraries are only available in .a format, you will not be able to compile GridFlow. All libraries GridFlow uses must be in .so format.

Downloading from CVS

The CVS has the absolute latest version of GridFlow, but it's not guaranteed to be working, whereas the actual releases are more tested.

However you may have various reasons to use the CVS edition, so here's how:

Make sure you have the cvs and ssh programs installed. (On MacOS, they are part of the DevTools CD)

mkdir -p ~/src/gridflow (make a directory; it could be called otherwise if you like)

cd ~/src/gridflow (go in that directory)

cvs -d :pserver:anonymous@artengine.ca:/home/cvs/gridflow login (the password is blank)

cvs -d :pserver:anonymous@artengine.ca:/home/cvs/gridflow checkout . (download the first time)

And the subsequent times, you only do this:

cd ~/src/gridflow

cvs update -dP

Installation process (for jMax 2.5.1 and compatible)

• 1 : if you don't have jMax, get it at jMax's site .
• 2 : Install Ruby 1.6.6 or any version released in 2002 or later (the latest from the 1.7/1.8 series work and are faster) You will need either libruby.so or libruby.a or libruby-static.a If you're using an installer and you're missing those files, then look for another package of a similar name that may contain extra files (eg: "ruby-dev"). If you're installing from source code you have to configure with the --enable-shared option. If you install into a system directory, you have to recreate the library index using the ldconfig command too (auto-installers normally do this for you).
• 3 : Download the latest version of GridFlow and download the images pack (gridflow-images-0.5.tar.gz). The download site is artengine.ca. Unpack Gridflow in /usr/local/jmax/packages (or the path of your choice), which will create a directory called 'gridflow'; unpack the images pack into that directory, which will create another one called 'images'.
• 4 : Run ./configure from the gridflow directory. ./configure will try to detect some optional components (libmpeg, pentium clock, etc). In the end, the files config.make, config.h and Makefile will be generated.
• 5 : If you are not running Linux on a PentiumPro-compatible computer, you will have to specify a jMax Makefile using the --jmax-arch option. This is the one you use when installing jMax (or other jMax plugins other than GridFlow) manually. On MacOS 10, this would be ppc-macosx.
• 6 : Stay in the same directory and do:
  • 1 : make
  • 2 : make install
  • 3 : make test
  but if one stops because of "Error" you shouldn't try the next one.
• 7 : Load ~/.jmaxrc (text). Go to the when start section. Add a line that says package require gridflow. Add this line that says dataDirectory gridflow-directory/images
• 8 : (Re)start jMax.

Note: you can do ./configure --help to get a list of supported options. You can use them to ignore the presence of troublesome libraries and select debugging level.

--use-compiler compiler normally would be one of: g++ g++-2.95 g++-3.2 g++-3.3. Do not use something with gcc in the name, as it results in undefined symbol problems.

Installation process (with jMax 4.1.0 and compatible)

Installation process (with PureData 0.35 and compatible)

• 1 : make sure m_pd.h is installed and can be seen by the compiler. you may have to change the C_INCLUDE_PATH environment variable.
• 2 : go in GridFlow's source directory.
• 3 : run ./configure
• 4 : run make
• 5 : run make install
• 6 : run make test
• 7 : run pd with the -path to the extras directory and -lib gridflow, or put those options in your ~/.pdrc file. (this part is essentially the same as GEM's and PDP's)

Installation process (without jMax nor PureData)

• 1 : If you don't have jMax installed it won't be detected. Installation will proceed normally except that the Ruby-for-jMax bridge won't be installed. Try running 'make test'. Look at 'tests/test.rb' for an example of how you may use GridFlow without jMax.

Installation process (MacOS 10.2)

DevTools: you need the DevTools CD. I tried the december 2002 edition. You can download that from Apple.

I've had a strange problem, in that the header files of Ruby (/usr/lib/ruby/powerpc-darwin6.0/*.h) didn't install at first, and when I tried reinstalling, the installer told me there was some more megs of files left to install, and then installed the header files of Ruby among other things.

Even then, that version of Ruby is missing the static library and the shared library, or in other words you can't build a jMax/PD plugin that uses Ruby with that. So I had to install Ruby myself. I picked some 1.8 version and configured with --enable-shared which is an essential option in this case it seems.

To be able to open a window in GF/OSX you need to do one of these:

• 1 : Install Apple X11 from http://www.apple.com/macosx/x11/
• 2 : Install FINK from http://fink.sourceforge.net/. Start the FinkCommander. Select xfree86-rootless and click on +A and +H. To start X11 in rootless mode on OSX, run this command: X :0 -rootless &. This version of X11 will require a "window manager", while Apple's X11 does not. The bundled one is twm, but if you're not into retro, you better download a better one.

If [@out window] doesn't work ("no such file or directory" ??) then you may have to set the DISPLAY environment variable. This is done by adding export DISPLAY=:0 in ~/.bashrc or setenv DISPLAY :0 in ~/.cshrc.

Additional support packages you could install from Fink before installing GridFlow: libjpeg libjpeg-shlibs libpng-shlibs libpng3 libpng3-shlibs libmpeg libmpeg-shlibs

Note: Fink installs stuff in directory /sw, which should be added to C_INCLUDE_PATH and LD_LIBRARY_PATH and such.

GridFlow should be configured with option --jmax-arch=ppc-macosx if you are going to use jMax.

Other Tips

• 1 : you just did a CVS update and now the program does not compile, or crashes, or changes didn't go through.
  • 1 : Did you forget the "make install" step?
  • 2 : If a new directory is created, you need to do cvs update -d. Many people just add that option to their configuration of the CVS software.
  • 3 : When some kinds of changes have happen, you may have to rerun the configure program before redoing make. If you had previously reconfigured with specific options, don't forget to use them again in this case.
  • 4 : Maybe matju forgot to checkin part of an important change. Tell him.
• 2 : Crashing:
  • 1 : you should know where the FTS executable file is. Its filename looks like "/usr/lib/jmax/fts/bin/i686-linux/opt/fts". we'll call it $FTS now.
  • 2 : if you want to prevent a complete machine crash, you should not run fts as "root" user, and you should do chmod u-s on the $FTS file. I recommend that you work that way until the fts crash problem is fixed, and only run it again as root only when you have a good reason to do so.
  • 3 : by running the command "ulimit -c unlimited" before starting jmax (from the same shell) will cause a crash to write the program's RAM into a file named "core" in the current directory. The filename may vary slightly, for example it may be suffixed with a unique number.
  • 4 : you can read this file in a semi-friendly way by doing "gdb $FTS core" right after that. what you need to do with that is usually just to type "backtrace" and then "quit". the first command will print a list of functions active during the crash. the bug is usually in one close to the top of the list.
• 3 : Corrupted jMax file:
  • 1 : remember that FTP transfers in ASCII mode only work on certain kind of files, to transform them from Windows flavour to Unix flavour and back. It is completely irrelevant to .jmax files (as well as most image/sound/movie files) and if used in such a case it is harmful. You have to redownload using the other mode called binary which does not change the file at all.
  • 2 : files saved by jMax 4 cannot be reloaded in jMax 2.5; I currently have no cure for this other than to still edit with jMax 2.5. I estimate that it would be rather easy to create a converter from one variant to another. Contact me (matju) if you need to convert from version 4 to version 2.5.
  • 3 : CVS conflict: CVS may try to merge differences between jmax files as if they were text files, if CVS is not aware that it shouldn't do anything special with them. Same may happen with other kinds of files. Fortunately, your previously working file is renamed as hidden file with a ".#" prefix. The new working file is available by removing the corrupted one and doing cvs update again.

GridFlow 0.7.6 Documentation
Copyright © 2001,2002,2003 by Mathieu Bouchard matju@artengine.ca