Compiling Amaya Sources with Autoconf

The Amaya project is no longer maintained by W3C.

 

 

 

This document explains how to compile the Amaya environment (schemas compilers and the binary) from the distributed source tree.

Here is the content of this document:

1. Prerequisite
2. How to build
3. More info on the make files
4. More info on the build process
5. If make failed
6. If amaya binary doesn't work

Prerequisite

• It is strongly recommended that you use a GNU make and if possible GNU CC since these are the tools used by the Amaya Team, and very few tests have been done with other flavours of make and C compilers.
• The usual Unix development tools, including at least sed, awk and cpp should be available.
• Amaya requires wxWidgets (see What do I need to compile this version ?).
• In order to enable this option, you will need to download the amaya-sources.

  See AmayaWX.html.

How to build

Here is a simple recipe explaining how to build using autoconf:

1. If you have downloaded the source tar file, you have to create Amaya, redland, wxWidgets, Mesa and libwww subtrees with one of the following commands:
   • gunzip -c /tmp/amaya-sources-xxx.tgz | tar xvf-
   • tar xzvf /tmp/amaya-sources-xxx.tgz
2. If you are compiling on 64-bit platform, you have to change the current Mesa configuration file:

   In the source directory Mesa/configs/ overwrite the current file with a copy of linux-x86-64-static (or a more appropriated configuration file).

3. Create a subdirectoryfor your platform under the Amaya directory (e.g. WX)
4. cd to this subdirectory, then ../configure to create the Makefile(s).

   Configure accepts some specific parameters allowing to select packages to be compiled:

         --prefix=path             parent directory of the Amaya directory
                                   used by amaya script to launch the binary
                                   (by default /usr/local)
         --enable-system-raptor    use the system libraptor (recommanded)
         --enable-system-libwww    use the system libwww (not recommanded
                                   WebDAV doesn't work with system libwww
   
         --with-wxdebug            build wxWidgets lib with debug informations
         --with-debug              build Amaya with debug informations (-g -DAMAYA_DEBUG)
   
         --disable-svg             build Amaya without SVG support
         --disable-annot           build Amaya without Annotations support
         --disable-generic-xml     remove Generic XML support
       

   Configure creates all the Makefiles needed and generates a file Options.orig containing all the variable which can be tuned.

   If an Options file exists it's not modified by configure, but it's used by make. This allows you to keep your previous options when you do a new configure.

5. Edit the Options file as needed. If it doesn't exist edit the Options.orig file.

   For example one can just change the CFLAGS values.

   With -g the obj tree can grow up to 100 MBytes while without it it won't use more than 20 MBytes.

   The Options (or Options.orig) file also gives some hints on how the source tree is configured.

6. Build everything:

   "make all"

   It is strongly recommended to use GNU make, which may not be the default make on your system. In this case try:

   "gmake all", or "gnumake all", or "gmake MAKE=gmake all", or "make SHELL=/usr/bin/bash"
       

   The compilation process can take a fair amount of time, 10 minutes at least.

   You can test the result immediately by launching Amaya binary built in the bin directory:

   bin/amaya
       

7. If amaya binary seems fine you can install it:

   script_install

   By default, links to binaries are installed in /usr/bin, binaries and data are in $PREFIX/Amaya. This can be overridden by specifying different values for prefix(es) using configure command line options in step 2.

   Ultimately, if you're not satisfied with your current Amaya installation, you can clean up with:

   script_uninstall

More info on the make files

All the Makefile(s) build in the object tree are generated by configure script and Makefile.in templates found in the source tree. It generates a main Makefile at the top of the object tree and a set of Makefiles in most of the directory of the object tree. The main Makefile accepts the following targets:

• make rebuild : rebuild all the Makefile(s) from the autoconf and Makefile.in files.
• make depend : rebuild all the dependencies in the object tree.
• make proto : rebuild all the prototype include files xxx_f.h from their xxx.c counterpart.
• make clean : removes all object files, but keep the binaries in Amaya/obj /bin .
• make without argument rebuild amaya and print.
• make amaya rebuild only amaya.

One can also go to a specific subdirectory in the object tree and launch make from that place. It will rebuild all the objects pertaining to this directory.

If make failed

Errors may append at different stages in the compilation process. Here is a small checklist:

• From the start: typing make in the Amaya/obj directory doesn't work. This means that the step 1 or 2 of the previous section failed.
  1. Do you use GNU make? The Makefile organization heavily relies on including sub-Makefiles and some old versions of Make don't support it.
  2. Do you have write access on the Amaya/obj directory ?
  3. Do you have all mandatory sources ?
• An error when compiling a C file occurred:
  1. Check that you have some room left for the object.
  2. Verify the include path for the X-Windows and Motif include files in Amaya/obj /Options.
  3. Verify that the target directory for the object exist and is writable. The object name is shown in the make output behind the -o flag.
  4. Check that you are using an ANSI compliant compiler, while the code should compile with non-ANSI ones, we don't test this feature on a regular basis.
  5. If the error occurs when compiling a C file in the amaya directory, check that all the compilers invocations in steps 7 to 11 did not produce any error (the Thot compilers are verbose so errors messages may not be easily detected).
  6. Otherwise your best bet is to report the problem to the Amaya development Team, by sending the error to the www-amaya-dev@w3.org mailing-list. Please check first the archive, the error may have been already reported.
• An error occurred while running a compiler schema:
  1. Check that the compilers were properly built. Check with ldd that there is no missing shared library, e.g:

     ldd bin/app

  2. Check that cpp preprocessor is in the PATH. You can use the following shell script in conjunction with gcc, name it cpp, put it in the PATH with 755 Unix rights:

     #!/bin/sh
             exec `gcc --print-prog-name=cpp` $@

  3. Check that you have write access on Amaya/amaya directory.
  4. You can force the compiler to rebuild the Amaya and HTML schemas by typing:

     touch ../amaya/*.S

     touch ../amaya/*.A

     make amaya

• An error occurred at link time:
  1. Check that the precompiled libraries are not corrupted. In case of a corrupted library, one can re-extract it from the distribution file or rebuild it by giving one of the appropriate commands:

     make depend

     make

  2. If your linker is not able to find out graphic libraries you can try to specify "../libjpeg.a" instead of "-ljpeg", etc.
  3. Verify the library path (-L flags in LINK_OPTIONS) for the X-Windows and other libraries files in Amaya/obj /Makefile.
  4. Check whether -lSM and -lICE X11R6 libraries are needed. These were not needed (available) when working on an X11R5 environment.
  5. Your system can require an additional library "-ldb" (Dec-Alpha running Tru64-Unix, 4.0F, with the Freeware-CDROM V 2.3 installed seemed to require it).
  6. Otherwise your best bet is to report the problem to the Amaya development Team, by sending the error to the www-amaya-dev@w3.org mailing-list. Please check first the archive, the error may have been already reported

If the amaya binary doesn't work

Here is a few rules to check if the amaya binary just produced does not start:

1. Check that the shared libraries needed by amaya are found on the system. The command

   ldd bin/amaya on Suns or Linux

   chatr bin/amaya on HP's

   should print all the shared libraries needed by amaya and the path to the corresponding libraries in the system.

2. Check that the amaya compiled schemas are present, namely Amaya/amaya/HTML.STR, Amaya/amaya/HTMLP.PRS...
3. Verify that the main registry file Amaya/config/unix-thot.rc is present.
4. You can debug the problem by using a system call tracer like truss on Solaris or strace on Linux strace amaya).

All the remaining techniques for finding out what's wrong are software debugging methods. For this you will need to recompile the binary with the debug option enabled (--with-debug), and use a debugger program to see what's happening exactly. Once a bug has been identified, please report it to the Amaya development Team, by sending the error to the www-amaya-dev@w3.org mailing-list. But first please check the archive as the error may have been already reported. Of course, sending a contextual diff of the modified files may help in correcting the problem, and having it patched in the next release.