MAINTAINERCLEANFILES tweaks to remove some of the machine generated files

[geda-gaf.git] / README.win32

gEDA / gaf - MinGW

GPL Electronic Design Automation  
--------------------------------------------------------------------------
To run the binary distribution of gEDA/gaf - MinGW:

Remove any previous version of gEDA/gaf - Cygwin (or older build of the
mingw version).

You should not have to install anything else other than the .zip or .exe for 
gEDA/gaf.  gEDA/gaf - MinGW is fairly self contained.

1) Grab geda-mingw32-VERSION.zip and unzip it into c:\   At this stage
   in the game, it really should be in c:\  Unzipping the zip file
   should create a directory called "geda" (c:\geda)

2) Set the following environment variables:
        TMP     (some temp directory, say C:\TEMP , make sure this dir exists)
        HOME    (some home directory, say C:\ , make sure this dir exists)

3) Add c:\geda\bin to your PATH variable

4) Run gschem by typing: gschem  in a cmd window.  It should run.  If not
   please e-mail ahvezda@geda.seul.org with the error message.  You can
   also create a shortcut on the desktop to the binary, just change the
   Run option to run "minimized" if you don't want to see the console.

Please keep in mind that this port is really new and may do really
stupid things.  PLEASE BACKUP ANY DATA YOU VALUE.  gEDA/gaf - MinGW
(or any gEDA software) comes with NO WARRANTY (I hate having to say this).
Please let me know if there are any problems.

---------------------------------------------------------------------------
Recommended (but optional if you install into c:\geda)
Required (if you install into some other directory than c:\geda)

If you want to put the geda directory somewhere else, then you can do
that too, but you will need to set the environment variable:

GEDADATA 
to 
[new_path_to_geda]\geda\share\gEDA       

Examples:
set GEDADATA=c:\gnu\geda\share\gEDA
set GEDADATA=d:\geda\share\gEDA

Do not forget to put [new_path_to_geda]\geda\bin into 
your PATH.  You also need to set: 

GUILE_LOAD_PATH 
to 
[new_path_to_geda]\geda\share\guile\1.4.1

Getting these environment variables right is best done by trial and error.
You will know when you got it right when 1) gschem starts and doesn't 
complain, and 2) you can place components (via Add/Component...).

--------------------------------------------------------------------------
The rest of this readme describes how to build gEDA/gaf (gschem and
friends) on a win32 machine (WinNT/Win2K/WinXP).  It uses mingw32 as the
layer between win32 and the unix world (ie gcc, make etc...).
A useful reference to various porting issues is:
http://gnuwin32.sourceforge.net/compile.html

gEDA/gaf should build and run out of the box if you follow these
instructions.  

* If any part of this document is unclear, please post on geda-dev. 
* If any part of this document is wrong, please post on geda-dev. 
* If you are not familiar with compiling programs, please use a 
  binary distribution of gEDA/gaf - MinGW.

It is recommend that gEDA/gaf and all libraries are installed into c:/geda
If you want an alternative location, make sure all dependancies are installed
into the new location as well.

For this doc, a "%" is the bash shell prompt from msys.
Build instructions for gEDA/gaf - MinGW (gEDA running on Win32 machines)

But first an important warning:

These instructions assume the user has a significant amount of knowledge
of build unix programs under mingw32.  You need to be familiar with
the ./configure process, installing mingw32 properly, and resolving the
occasional build bug.

--------------------------------------------------------------------------

1) Download:

   Build environment
        * MSYS-1.0.7-i686-2.exe (http://www.mingw.org)
                                (use the proper ?86 version for your CPU!)
        * MinGW-1.1.tar.gz      (http://www.mingw.org)

   External libraries part of build environment
        * zlib-1.1.3-1.zip      (https://sourceforge.net/projects/mingwrep/)
        * readline-4.2-20010727.zip
        * regex-0.12-20010123.zip
        * rx-1.5-20010502.zip
        * libpng-1.0.6-20000724.zip 
        * libpng-devel-1.0.6-20000724.zip
                  ---OR---
        Grab the corresponding .tar.gz files for the above .zips from:
        http://www.geda.seul.org/devel/win32/build
        
  gEDA/gaf guile library (from http://www.geda.seul.org/devel/win32/mingw)
        guile-1.4.1-gaf.tar.gz  

  gEDA/gaf gtk/glib libs (from http://www.geda.seul.org/devel/win32/mingw)
        gtk+-1.3.0-20020313-gaf.tar.gz  

  gEDA/gaf itself (http://www.geda.seul.org/devel)
        geda-gnetlist-VERSION.tar.gz
        geda-gschem-VERSION.tar.gz
        geda-gsymcheck-VERSION.tar.gz
        geda-symbols-VERSION.tar.gz
        geda-utils-VERSION.tar.gz
        libgeda-VERSION.tar.gz
        Makefile

  gEDA/gaf optional libraries (http://www.geda.seul.org/dist)
        libstroke-0.5.1.tar.gz  

  Any VERSION >= 20020527 should build under MinGW.

2) Install MSYS by running:

        MSYS-1.0.7-i686-2.exe

3) Double click on the Msys icon on the desktop to get a shell (bash prompt)

4) Install Mingw (the compilers, development environment, and libraries)
        % cd /
        % mkdir mingw
        % cd mingw      !! This step is important; do not untar in / !!
        % tar xvfz MinGW-1.1.tar.gz

   Unzip the other .zip files using winzip or use the .tar.gz I provided.
   If you decide to unzip the .zip files, then unzip directly into
   c:/msys/1.0/mingw (the mingw directory).

        % cd /mingw     !! This step is important; do not untar into / !!
        % tar xvfz zlib-1.1.3-1.tar.gz
        % tar xvfz readline-4.2-20010727.tar.gz
        % tar xvfz regex-0.12-20010123.tar.gz
        % tar xvfz rx-1.5-20010502.tar.gz
        % tar xvfz libpng-1.0.6-20000724.tar.gz 
        % tar xvfz libpng-devel-1.0.6-20000724.tar.gz
        % cd bin
        % mv make.exe makeold.exe

   Doing the last step is very important.  The make.exe in /mingw/bin is 
quite pathetic.

   You may see an error message like doing the untar operations:

tar: Child died with signal 13
tar: Error exit delayed from previous errors

   I checked and all the files untarred okay, your milage may vary.

5) Build a test program (like hellow) to test the compilers
   You can use vi to input the code or your favorite editor.

--- Cut here for hellow.c ---
#include <stdio.h>

int
main(int argc, char **argv)
{
   printf("Hello World!\n");
   return 0;
}
--- Cut here for hellow.c ---

   Build it like this: 
        % gcc -o hellow hellow.c
   Run it: 
        % ./hellow  

   If this does not work.  Do not continue until you have fixed any problems.

6) Create the destination install directory
        % mkdir c:/geda
        % ls c:/geda

7) Add c:/geda/bin to your path in your msys shell

        % export PATH=/c/geda/bin:$PATH

        Use /c/... not c:/...

8) Build guile-1.4.1-gaf

   guile-1.4.1-gaf is a hacked version of guile-1.4.1 for gEDA/gaf 
   and the Mingw port.  Please don't use it unless you are building gEDA/gaf.
   For the real thing (real guile), please see http://www.gnu.org

   Make sure you have installed all the *.tar.gz library files mentioned
   above before doing this step. 

        % cd
        % tar xvfz guile-1.4.1-gaf.tar.gz
        % cd guile-1.4.1-gaf
        % ./configure --prefix=c:/geda --enable-posix --enable-regex --without-modules --enable-guile-debug --without-threads --disable-networking --enable-ltdl-convenience 
        % cd libltdl 

        Edit the Makefile in libltdl searching for -I. change one of these to
        -I.. (two periods, parent directory; this fixes the "cannot find 
        libguile.h").

        % make
        % cd ../ice-9
        % make install

        You might get an error about and-let-star.scm or and-let-*.scm; 
        I ignored it.

        % cd ../guile-config
        % cp guile-config.geda guile-config
        % cd ../libguile
        % make libpath.h
        % make -f Makefile.Win32 install

   Guile errors and workarounds.  You may or may not see these.

        * ./configure error:

checking whether make sets ${MAKE}..... ./configure: eval: line 1: unexpected EOF while looking for matching `"'
./configure: eval: line 2: syntax error: unexpected end of file
no
        I ignored it. :-)
        
9) Post guile install steps and test

   Copy a few dlls into c:\geda\bin
        
        % cd /mingw/bin
        % cp librx.dll c:/geda/bin
        % cp libreadline.dll c:/geda/bin
        % cp libregex.dll c:/geda/bin
        % cp libz.dll c:/geda/bin
        % cp libpng.2.1.dll c:/geda/bin 

        Make sure that libguile.dll got installed in c:\geda\bin
 
   Open up a cmd shell (dos command box) and do the following:

        Add c:/geda/bin to your path:
        c:\> set PATH=%PATH%;c:\geda\bin 
        c:\> guile.exe

   At this point you should see a guile> prompt.
  
        guile> (display "Hello World!") (newline)
        guile> (quit)

   Try building a very basic guile program:

-- Cut here for gtest.c --
#include <guile/gh.h>

void main_prog(int argc, char *argv[])
{
  scm_shell(argc, argv);
}

int
main(int argc, char **argv)
{
  gh_enter(argc, argv, main_prog);
  return 0;

}
-- Cut here for gtest.c --

   Build it like this:

   % gcc -o gtest gtest.c `guile-config compile` `guile-config link`

   Run it:

   % ./gtest
   guile> (display "gtest") (newline)
   guile> (quit)

   If the above steps do not work, please go back and get this working,
   otherwise the following steps will not work either.


10) Untar gtk

        % cd $HOME
        % tar xvfz gtk+-1.3.0-20020313-gaf.tar.gz

   This will create $HOME/gtk.  If you untar in a different location you 
   will need to change gtk/bin/gtk-config and gtk/bin/glib-config. 

   gtk+-1.3.0-20020313-gaf.tar.gz is a repackaged version of Tor Lillqvist's 
   "gtk+ for Win32".  I (Ales) repackaged to make build life easier for
   gEDA/gaf users.  Without Tor's work, gEDA/gaf - MinGW would NOT
   be possible.

        % cd gtk/lib
        % cp *.dll c:/geda/bin
        % cd ../bin
        % cp gtk-config glib-config c:/geda/bin

11) Test gtk

        Use the following test program (ghellow.c) to test gtk on your system.
(This test program came from the gtk-1.2 tutorial, helloworld.c)  You can
find ghellow.c in $HOME/gtk. 

-- Cut here for ghellow.c -- 
      #include <gtk/gtk.h>

      /* This is a callback function. The data arguments are ignored
       * in this example. More on callbacks below. */
      void hello( GtkWidget *widget,
                  gpointer   data )
      {
          g_print ("Hello World\n");
      }

      gint delete_event( GtkWidget *widget,
                         GdkEvent  *event,
                         gpointer   data )
      {
          /* If you return FALSE in the "delete_event" signal handler,
           * GTK will emit the "destroy" signal. Returning TRUE means
           * you don't want the window to be destroyed.
           * This is useful for popping up 'are you sure you want to quit?'
           * type dialogs. */

          g_print ("delete event occurred\n");

          /* Change TRUE to FALSE and the main window will be destroyed with
           * a "delete_event". */

          return(TRUE);
      }

      /* Another callback */
      void destroy( GtkWidget *widget,
                    gpointer   data )
      {
          gtk_main_quit();
      }

      int main( int   argc,
                char *argv[] )
      {
          /* GtkWidget is the storage type for widgets */
          GtkWidget *window;
          GtkWidget *button;
          
          /* This is called in all GTK applications. Arguments are parsed
           * from the command line and are returned to the application. */
          gtk_init(&argc, &argv);
          
          /* create a new window */
          window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
          
          /* When the window is given the "delete_event" signal (this is given
           * by the window manager, usually by the "close" option, or on the
           * titlebar), we ask it to call the delete_event () function
           * as defined above. The data passed to the callback
           * function is NULL and is ignored in the callback function. */
          gtk_signal_connect (GTK_OBJECT (window), "delete_event",
                              GTK_SIGNAL_FUNC (delete_event), NULL);
          
          /* Here we connect the "destroy" event to a signal handler.  
           * This event occurs when we call gtk_widget_destroy() on the window,
           * or if we return FALSE in the "delete_event" callback. */
          gtk_signal_connect (GTK_OBJECT (window), "destroy",
                              GTK_SIGNAL_FUNC (destroy), NULL);
          
          /* Sets the border width of the window. */
          gtk_container_set_border_width (GTK_CONTAINER (window), 10);
          
          /* Creates a new button with the label "Hello World". */
          button = gtk_button_new_with_label ("Hello World");
          
          /* When the button receives the "clicked" signal, it will call the
           * function hello() passing it NULL as its argument.  The hello()
           * function is defined above. */
          gtk_signal_connect (GTK_OBJECT (button), "clicked",
                              GTK_SIGNAL_FUNC (hello), NULL);
          
          /* This will cause the window to be destroyed by calling
           * gtk_widget_destroy(window) when "clicked".  Again, the destroy
           * signal could come from here, or the window manager. */
          gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
                                     GTK_SIGNAL_FUNC (gtk_widget_destroy),
                                     GTK_OBJECT (window));
          
          /* This packs the button into the window (a gtk container). */
          gtk_container_add (GTK_CONTAINER (window), button);
          
          /* The final step is to display this newly created widget. */
          gtk_widget_show (button);
          
          /* and the window */
          gtk_widget_show (window);
          
          /* All GTK applications must have a gtk_main(). Control ends here
           * and waits for an event to occur (like a key press or
           * mouse event). */
          gtk_main ();
          
          return(0);
      }
-- Cut here for ghellow.c -- 

   Build it:

        % gcc -o ghellow ghellow.c `gtk-config --cflags --libs`

   Run it:
        
        % ./hellow

   If it fails to run, the fix the problem before continuing.  As usual, if
   the test program does not link and run, then you will NOT be able to build
   and run gEDA/gaf.

12) Build and install libstroke into /mingw

    Build and install libstroke if you want stroke support in gschem.

        % tar xvfz libstroke-0.5.1.tar.gz
        % cd libstroke-0.5.1

        Edit configure script commenting out the following:

#if test "$X11LIB" = no; then
#        { echo "configure: error: Cannot find -lX11 library" 1>&2; exit 1; }
#fi

        % ./configure --prefix=/mingw --disable-gtktest --disable-tcl
        % cd libstroke
        % make install

        Install libstroke into /mingw and not c:/geda since it will make 
gEDA/gaf's build much easier.

13) Build/install gEDA/gaf itself

    Untar all of the gEDA/gaf tarballs into a directory.
    Put that Makefile into this toplevel directory.

    Edit the Makefile so that: 

CD_VERSION=-$(VERSION)
DIR_PREFIX=geda-

    is commented in.  And that the prefix in the Makefile is set to:

prefix=c:/geda

    Also make sure the VERSION variable is correct.

    Start the build:

        % make install

    You may see the following errors:

        * ./configure error:

checking whether make sets ${MAKE}..... ./configure: eval: line 1: unexpected EOF while looking for matching `"'
./configure: eval: line 2: syntax error: unexpected end of file
no
        I ignored it everytime.
        
   The symbols are installed twice for some odd reason.

   If everything completes okay (no FATAL errors), then 
gEDA/gaf - MinGW has build successfully.  Congratulations.


--------------------------------------------------------------------------
   The MinGW port has been brought to you by many many months of work, 
several crashed Windows machines (seriously), and a few close calls where
I almost gave up on the port. :->