Compile and Install Instructions for Magic

Table of Contents

Magic Compile and Install From Source
Magic Precompiled Packages Installation
Windows Version Installation
Debugging Runtime Problems

Compiling and Installing Magic From Source

While it is true that most people want to install and run an executable "out-of-the-box," without worrying about compiling, it is also true that EDA tools are complicated, require a lot of care and maintenance, and usually work best when compiled from the original source code. The developers go to great lengths to make sure that the source code will compile on various systems without trouble.

In the current (8.3) distribution, compile and install instructions can be found in the INSTALL file in the top-level directory of the source distribution.

In releases prior to 7.4, see the file README.Tcl in the source distribution for complete instructions on compiling the Tcl/Tk-based version of magic.

For the impatient, the general rule is:

% ./configure % make % make install

Support for the interactive script "make config" is deprecated; use the GNU autoconf script. The "make config" option was completely removed from version 7.4. Also since version 7.4, the final output of "configure" reports the status of key requirements, and suggests what might need to be done to correct problems with key requirements not being found. More detailed information on solving configuration problems can be found below.

Word of warning: Some of the compile-time scripts are not thread-safe, so do NOT use, e.g., "-j4" or "-j8" as an option to "make", or else some of the automatically generated files can get screwed up. Magic is written in plain C, so the compile time is very fast even as a single thread process.

System Requirements

These comments were helpfully provided by Jason Schonberg, January 2010. Although specifically for Ubuntu Linux, they provide a good summary of the packages required on all systems. Different distributions of Linux may or may not come with all of the following packages, and missing ones will need to be installed.

Updated October 2018. The reference to BLT has long been deprecated since most BLT functions were absorbed into the Tk distribution. Added the package dependency for the Cairo graphics package (for magic-8.2).

In order to compile Magic on a vanilla installation of Ubuntu, the following additional packages are needed (at a minimum):

M4 preprocessor

$ sudo apt-get install m4

python 3

$ sudo apt-get install python

Xlib.h

$ sudo apt-get install libx11-dev

If you wish to have the Tcl/Tk wrapper around magic (recommended) you will need to install the Tcl/Tk libraries. Version 8.5 or higher is highly recommended.

Tcl/Tk

$ sudo apt-get install tcl-dev tk-dev

The best graphics for Magic is the OpenGL interface ("magic -d OGL"), but since that is problematic for off-screen rendering on many systems, a good alternative is the Cairo graphics interface ("magic -d XR"). This is optional, but if you want to use it, you need the Cairo library development package:

Cairo

$ sudo apt-get install libcairo2-dev

The OpenGL interface itself may need these dependencies:

OpenGL

$ sudo apt-get install mesa-common-dev libgl-dev libglu1-mesa-dev

The zlib compression library allows the creation and reading of compressed (gzipped) GDS files and the reading of compressed .mag files:

ZLib

$ sudo apt-get install zlib1g-dev

For the non-Tcl/Tk version only: The readline source makes reference to the `tputs` function which is provided by the ncurses library. Although the ncurses library is installed in Ubuntu, the include files to build against it are not, so the development version is required.

ncurses

$ sudo apt-get install libncurses-dev

GNU Autoconf Compilation: Hints for "configure"

Compile-time options can be queried by doing "configure --help". The major options, which one might have reason to invoke, are as follows:

--help

List all of the compile-time options.

--prefix=DIR

Set the install destination to directory path DIR. The default installation destination is /usr/local. Magic will be installed in various subdirectories of the prefix, such as /bin for executables and /lib for run-time files (technology files, startup scripts, display settings, etc.). This is especially useful to install magic in a local directory to avoid requiring root privileges to install, or to install a test version of a new release of magic which won't conflict with any existing installed versions.

--libdir=DIR

Specify the install location of run-time files. On systems where the run-time files and the executables have the same root directory ${prefix}, ${libdir} is ${prefix}/lib and exectutables are installed int ${prefix}/bin. When runtime files are to be installed somewhere else, for example, /usr/share in some distributions, ${libdir} must be set with this switch.

--with-interpreter=TYPE

Compile magic with an interpreter. Possible values of TYPE are tcl, scheme, or no. The default compilation is to use Tcl/Tk if found, or no interpreter otherwise. Use this option only to force a non-Tcl-based compile. Generally, the Tcl/Tk-based version is preferred, due to the large number of enhancements available under the TCL version (such as the GUI frontend).

--with-distdir=DIR

Specify an install location that is different from where magic will be at run-time. That is, if magic is going to be installed to a local filesystem and then distributed to another filesystem, say through an NFS mount, then --with-prefix= should point to the path of magic as it is seen at run-time on the machines where it has been distributed, while --with-distir= should point to the location where it will be installed on the local machine where it is being compiled.

Some systems may run into trouble with the TCL interpreter, OpenGL, Cairo, or X11 if they are installed in unusual places. The autoconf script goes to great lengths to find them, but in case of failure, the location of files may be specified explicitly by passing an argument to autoconf.

--with-tcl=DIR

One of the most likely problems with configure is the inability to find Tcl/Tk libraries and/or header files. Usually this is due to having an executable-only version of Tcl/Tk (libraries but no header files), but it can also be due to having Tcl/Tk installed in an unexpected place. If header files are nonexistant, the solution is either to install them, or to compile the latest version of Tcl/Tk from source. Otherwise, if header files and libraries exist, then use the option above with DIR pointing to the directory containing the file tclConfig.sh.

--with-tk=DIR

Specifies the path to find the file tkConfig.sh. This is likely to be necessary if you need to use the --with-tcl= option.

--with-opengl=DIR

OpenGL capability is a runtime option. Magic defaults to the X11 interface; enable the OpenGL graphics by specifying "-d OGL" on the command line at runtime. This option is preferred when OpenGL libraries are available on systems with fast graphics and a hardware implementation of OpenGL on the video card. It is not recommended on systems running a software emulation of OpenGL calls, such as Mesa GL in conjunction with an unsupported video card. There is no reason not to compile in OpenGL support, and so it is enabled by default. If the OpenGL libraries and/or header files cannot be found, they may need to be downloaded from the video card vendor. If they exist but are in a non-standard location, the location of the header files can be specified by DIR.

--with-cairo=DIR

Cairo 2D rendered graphics capability is a runtime option. Magic defaults to the X11 interface; enable the Cairo graphics by specifying "-d CAIRO" or "-d XR" on the command line at runtime. This option is preferred when Cairo libraries are available on systems with fast graphics and vido card hardware acceleration. There is no reason not to compile in Cairo support, and so it is enabled by default. If the Cairo libraries and/or header files cannot be found, they may need to be downloaded from the video card vendor. If they exist but are in a non-standard location, the location of the header files can be specified by DIR.

--x-libraries=DIR

Specifies the path to find the X11 library files (e.g., libX11.so and so forth). This is usually not necessary but some platforms may put the X11 in an unexpected place. If so, it may also be necessary to specify --x-includes=DIR to point to the directory where X11 header files can be found.

--disable-locking

Disallow file locking for multiple-user environments (used with magic version 7.4). Magic 7.4 has a simplified file locking mechanism that does not create directories and files, but uses the fcntl advisory lock system. However, each locked file must remain open, and it is possible that some platforms may not allow enough open file descriptors, causing magic to be unable to open layout files. Should this happen, magic can be recompiled with file locking disabled.

--enable-framebuffer-backing-store

Normally OpenGL uses Tk pixmaps for managing backing store (graphics acceleration through saving and copying the screen image). Implementations of OpenGL that do not allow direct rendering to off-screen targets will require this to be enabled. If the cursor box doesn't erase but keeps getting drawn multiple times on the screen as it is moved around (in OpenGL graphics mode), then you need to enable this option.

--enable-cairo-offscreen

Usually if off-screen rendering doesn't work for the backing store (see above), then the generation of the layer images on the buttons in the GUI window doesn't work, either. If magic exits with an X11 server "Bad Drawable" error, then this needs to be enabled (and the Cairo libraries and include files need to be installed on the system).

--disable-client-render

Disable client-side rendering, when OpenGL has been selected as an optional graphics package. Some video drivers may not handle server-side rendering correctly, although this is pretty rare.

All of the optional modules in magic can be enabled or disabled by individual switches on the command line. Normally, these should be left alone.

--enable-locking

Allow file locking for multiple-user environments (used with magic versions other than 7.4). File locking allows layout databases to be accessed by multiple users. Only one user at a time may edit a layout file, preventing accidental overwrites. Because having this option turned on allows magic to create new directories for lock files, it is disabled by default. However, even with the option enabled, magic cannot create new directories unless a system-level directory "/usr/local/flock" has been created (it is not created by the install process). This directory must be world-writable.

--disable-readline

Disable the "readline" package. Note that the Tcl-based version of magic does not use "readline", so this option has no effect unless compiling with either the SCHEME interpreter or no interpreter.

--disable-threads

Disable the use of POSIX threads (pthreads) with the X11 graphics interface. This reverts back to the use of a forked "helper" program to capture graphics calls. This is unlikely to be necessary unless there is some suspicion of a thread-related lock-up.

--disable-nonmanhattan

Disable the non-Manhattan geometry extensions.

--disable-calma

Disable the GDS module. There is no reason to do this.

--disable-cif

Disable the CIF module. Note that this will also disable the GDS module, which depends on it. So there is no reason to do this, either.

--disable-lef

Disable the LEF/DEF format module.

--disable-plot

Disable the plot module.

--disable-route

Disable the various router modules (these can not be enabled or disabled individually).

--disable-rsim

Disable the IRSIM interface. Note that the Tcl-based version of magic interfaces with IRSIM through the interpreter, so this option has no effect unless compiling with the SCHEME interpreter or no interpreter.

--disable-new-macros

Disable the use of the new macros, reverting back to the macros used by magic versions 6.5 and earlier. Veteran users of Magic may prefer the older macros. The newer macro set, developed by Philippe Pouliquen, makes use of the keypad and cursor keys for directional actions such as "move" and "stretch". The older macro set mapped the keys "QWER" to directions.

For even more obscure options which may effect compilation on peculiar systems, refer to the text dump from "configure --help".

Note that distributions which require the use of "--libdir=DIR" may also need to use the equivalent "--mandir=DIR" to point to the manual pages directory. "--bindir=DIR" can be set likewise. However, if all three switches are used, then "prefix" no longer has any meaning, since its only use is to define the default values of libdir, mandir, and bindir.

Distribution Maintainers: Those maintainers who wish to compile in the so-called "sandbox" can do (as of Magic distribution version 7.4.6 and development version 7.5.4):

./configure [options]
make
make DESTDIR=staging_area install

This procedure will install everything into the specified directory tree rooted at staging_area, without breaking the hard-coded links to run-time files. To run Magic from the staging area, either chroot to the staging area directory, or set

setenv CAD_ROOT staging_area/libdir

where libdir is, by default prefix/lib, unless otherwised specified in the configure options, and prefix is by default /usr/local unless otherwise specified in the configure options.

A Note about Autoconf: The actual autoconf script is in the subdirectory scripts, but there is a top-level shell script wrapper called configure that invokes scripts/configure. Part of the purpose of the wrapper script is to allow much of the useless cruft that has to accompany the GNU autoconf files to be stuffed in an out-of-the-way subdirectory. The other is to set up the CFLAGS environment variable, so that the optimizer flag can be removed. Magic may run marginally faster with compile-time optimization; if you wish to enable it, then you may add "-O2" to CFLAGS in the top-level "configure" shell script. However, please note that optimized executables are very difficult to debug should something go wrong with the program during run-time.

A Note about Tcl/Tk: Compilation under Tcl/Tk is probably both the most common option and the most problematic. A number of standard OS distributions do not come with all the bits and pieces necessary to compile a Tcl/Tk extension. If this is the case, then you will see this when you do configure when it says:

checking for tclConfig.sh... no.

Assuming that you really, really want the Tcl version of magic (and in my opinion, you really, really do), your best bet is to download, compile, and install new versions of Tcl and Tk. This is pretty straightforward. Get the latest version from the Tcl/Tk Developers Exchange (click on the download link up near the top). One important thing to know when compiling your own: The executables for "tclsh" and "wish" will be installed as "tclsh8.4" and "wish8.4" (or whatever is the current version number). "wish" is critical, because magic uses it. You will need to rename or remove any existing executable for wish, and then either rename "wish8.4" to "wish" or else create a symbolic link "ln -s wish8.4 wish" (preferred).

For example, I had a RedHat system which came with Tcl/Tk 8.0 installed in /usr/bin/. Compiled from source, Tcl/Tk 8.4 installed by default in /usr/local/bin/. I changed "/usr/bin/wish" to "/usr/bin/wish8.0" and changed "/usr/local/bin/wish8.4" to "/usr/local/bin/wish" (hmm, did I just say "preferred"?).

Note that Magic version 7.2 compiled with Tcl makes use of the optional Tcl/Tk package "BLT". Magic will run fine without it (it detects its absence and works around it), but if you don't have it, you'll miss the "cell manager" widget with the hierarchical cell view. BLT can be downloaded from SourceForge at the following location: BLT Toolkit Project on SourceForge.

Installing Precompiled Packages

At this time, packages are only available for prior releases of magic. See the download page for available precompiled executables and packages.

Windows/Cygwin

The Windows/Cygwin version installation instructions can be found under a separate link for the Cygwin versions of various related EDA tools. These are in a separate section because all of them are Tcl/Tk-based, and the tools with graphical user interfaces require an X11-enabled version of Tcl/Tk, which must be installed first. To install magic for windows, start with this link:
Cygwin EDA Tools

Debugging Runtime Errors under Tcl

The Tcl version, especially using the console, can make debugging runtime errors difficult, especially if the error appears in the console and then the console is destroyed along with the interpreter as magic exits suddenly. Also, the convoluted way magic starts up under the interpreter means that some reported errors may not actually point to the correct origin of the error.

The methods described below progress from easiest to most difficult, but each can be useful depending on how and when the program bites the dust.

gdb "attach" method

The easiest method to debug magic is to use the "attach" function in gdb, which can be specified on the command line as:

gdb program ppid

If only one process using the Tk wish graphical shell is running, the following Linux shell command (which can be copied into a shell script, for convenience) will attach and run gdb on the magic process:

gdb program `ps -C wish --no-headers -o "%p"`

Although this is supposed to work according to the manual page for gdb, I find that gdb doesn't recognize any symbols unless I do:

ps -C wish --no-headers -o "%p"
gdb wish
attach process_id

using the result of the first command for process_id in the gdb attach command. On machines that don't recognize the "-C" switch to ps, use whatever variant that will show you the process ID of the "wish" executable.

Note that once gdb is running, the program may be interrupted at any point with a control-C key sequence in the terminal running gdb, to check variables, calling sequences, set breakpoints, etc. The gdb command "continue" resumes the program after attaching the debugger to the process. If you want the magic developers to investigate a segmentation fault, run the program under the debugger using the above method, and try to repeat the minimum number of steps leading to the crash. After the crash condition has caused the process to drop back to the debugger prompt, run the command "where" to get a stack trace of the subroutine call stack. Email this information to the developers, along with any other relevant information.

If the program fails during or after loading the technology file, but does not crash, it is still possible to use this method by attaching gdb, setting a breakpoint, then running

tech load tech_name

from the magic command line. The tech load command clears out most of the allocated memory structures used by magic and regenerates them from scratch as the technology file is loaded back in.

If the program crashes too fast to attach gdb to the running process, then one of the methods below may be necessary.

"noconsole" method

Errors which disappear along with the console can be viewed by running magic without the console:

magic -noconsole

To debug more pernicious runtime errors, it may be necessary to do a partially manual startup of magic. For non-fatal errors (i.e., an exit with an error but not a segmentation violation or bus error), do the following:

wish
source /usr/local/lib/magic/tcl/magic.tcl

Note that with this kind of manual startup, it is not possible (or at least, it's not easy) to use the "tkcon" console window.

standalone method

Sometimes it may be necessary to pass arguments to magic. An example follows:

wish
set argc 4
set argv {-d OGL -T scmos}
source /usr/local/lib/magic/tcl/magic.tcl

executable method

Magic has two versions that start as an executable stand-in for the "wish" and "tclsh" Tcl interpreter shells. These two can be run directly under gdb. One of them is magicexec and is normally invoked when running magic as "magic -noconsole":

gdb /usr/local/lib/magic/tcl/magicexec
run

The other is magicdnull and is normally invoked when running magic as "magic -dnull". It is not possible to create a layout window when using this version:

gdb /usr/local/lib/magic/tcl/magicdnull
run

manual object load method

Under some circumstances, it may be necessary to manually load the magic shared object file to figure out what went wrong. This is a good thing to do if, for instance, magic reports that it can't find the "tclmagic.so" file:

wish
load /usr/local/lib/magic/tcl/tclmagic.so
magic::start

For fatal errors (crashes), do the following:

gdb wish
run
source /usr/local/lib/magic/tcl/magic.tcl

Various combinations of the above tactics may be necessary to get the program to run in the right mode for reproducing the runtime error. Note that all of the examples above assume that magic has been installed in the default directory /usr/local, and proper substitutions should be made if required by a non-default location of the installation.

email:

Last updated: October 1, 2024 at 7:54pm