Merge fb85e97b92 into cc4da9a05f

README.md

@@ -1,44 +1,298 @@
+
+<h1 align="center">MAGIC</h1>
+<h2 align="center"> Magic is a venerable VLSI layout tool</h2>
+
+---
+
+
+<img src="assets/2021-12-22-21-23-08.png" width="400">
+<img src="assets/2021-12-22-21-23-33.png" width="400">
+
+---
 ![Continuous Integration](https://github.com/RTimothyEdwards/magic/actions/workflows/main.yml/badge.svg)
+---
 
-# MAGIC
+# Install Magic
+
+<img src="assets/2021-12-22-23-06-10.png" width="100">
+<img src="assets/2021-12-22-23-07-35.png" width="100">
+
+# (Ubuntu/Linux) Compile and install guide 
+## In order to install magic on Ubuntu/Linux follow these steps:
+<details>
+  <summary>Expand for more details</summary>
+
+## install prerequisits (Ubuntu) (Updated October 2018)
+<details>
+  <summary>Expand for more details</summary>
+
+```bash
+sudo apt-get install m4
+
+# note that Ubuntu has different csh and tcsh
+sudo apt-get install tcsh
+sudo apt-get install csh
+sudo apt-get install libx11-dev
+sudo apt-get install libcairo2-dev
+```
+# Install the recommended Tcl/Tk wrapper around magic   (Version 8.5 or higher is highly recommended.)
+```bash
+sudo apt-get install tcl-dev tk-dev
+```
+
+## non-TK alterantive (OPTIONAL)
+<details>
+  <summary>Expand for more details</summary>
+
+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.
+```bash
+sudo apt-get install libncurses-dev
+```
+</details>
+
+## Graphics alternatives (OPTIONAL)
+
+<details>
+  <summary>Expand for more details</summary>
+
+### 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
+```bash
+sudo apt-get install libcairo2-dev
+```
+### The OpenGL interface itself may need these dependencies:
+### OpenGL
+```bash
+sudo apt-get install mesa-common-dev libglu1-mesa-dev
+```
+</details>
+
+---
+
+</details>
+
+# Compile magic from source magic
 
 
-1. General Information:
+### example with no options:
----------------------------------
+```bash
-   Use your World Wide Web browser to read:
+cd ~
+git clone https://github.com/RTimothyEdwards/magic.git
+cd magic
+./configure 
+make
+sudo make install
+```
+#### Note: Remember to use 'gmake' on FreeBSD.
+---
 
-	http://opencircuitdesign.com/magic/
+## Options Details 
+---
+### Autoconf options (use `./configure --help` for a complete list):
 
-   Primary documentation is on the opencircuitdesign.com website under
+### example with no options:
-   various links, including "Download", "Compile", and "Install" for
+```bash
-   information on obtaining, compiling, and installing the tool from
+./configure <options>
-   source; "Code History" for detailed comments on all code changes;
+```
-   "Using Magic" for basic usage information including a complete on-line
+---
-   command reference;  "Technology Files" for essential documentation on how
-   to understand, edit, or write technology files for Magic; "Documentation"
-   for miscellaneous papers and historical documentation converted to HTML
-   format.
 
-   The current distribution version of magic is maintained by Tim Edwards
+### Indicates the install directory.  
-   <tim@opencircuitdesign.com>.  Please let me know of any problems/bugs
+#### Determines the install directory of the executable.  Determines the install directory of the libraries (${prefix}/lib) unless use of `--libdir=<DIRECTORY>` overrides it.  Defaults to `/usr/local/`.
-   you find through the github Issues tracker.
+```bash
+	--prefix=<DIRECTORY>	
+```
 
-   Additional information from developer Rajit Manohar:
+---
 
-	https://csl.yale.edu/~rajit/magic/
+### libdir
+#### By default, `${prefix}/lib/`.  Otherwise, run-time files used by magic are installed here, and ${CAD_ROOT} is set to DIR.  In some distributions, this is set to `/usr/share/`.
+```bash
+./configure --libdir=<DIRECTORY>	
+```
 
-   Of mainly historical interest only, now (available through the WayBack machine):
+---
 
-	https://web.archive.org/web/20051217204815/http://www.research.compaq.com:80/wrl/projects/magic/magic.html
+### Enable one of the two interpreters.
+#### one of "tcl" or "scheme".
+```bash
+./configure --with-interpreter=<"tcl" | "scheme">
+```
+
+---
+
+### Equivalent to "--with-interpreter=tcl".
+####      Normally enabled, if available.
+```bash
+./configure --with-tcl
+```
+
+---
+
+### Enable OpenGL as a graphics option. 
+#### Normally enabled, if available.
+```bash
+./configure --with-opengl
+```
+
+---
+
+### Disable X11 as a graphics option.  
+#### Normally enabled.
+```bash
+./configure --without-x	
+```
+
+---
+
+### Disable non-Manhattan extensions.  
+#### Normally enabled.
+```bash
+./configure --disable-nonmanhattan
+```
+
+---
+
+### Disable the GNU "readline" package.
+#### Normally enabled.
+```bash
+./configure --disable-readline
+```
+
+---
+
+### Disable threaded X11 and OpenGL graphics.
+#### Normally enabled.
+```bash
+./configure --disable-threads
+```
+
+---
+
+## For more on how to use magic visit the user guid here
+---
+### [Magic User's Guide](http://opencircuitdesign.com/magic/)
+
+---
+</details>
+
+---
+
+<img src="assets/2021-12-22-23-05-29.png" width="100">
+
+# (Mac) Compile and install guide
+
+## In order to install magic on MacOS (Big Sur) follow these steps:
+
+<details>
+  <summary>Expand for more details</summary>
+
+## Build Tcl for X11
+
+We are following the instructions from xschem [github.com/StefanSchippers/xschem.... README_MacOS.md](https://github.com/StefanSchippers/xschem/blob/master/README_MacOS.md). 
+
+#### Download Tcl from https://prdownloads.sourceforge.net/tcl/tcl8.6.10-src.tar.gz
+
+We are using not `opt` but `opt2` so that this Tcl does not interfere with `tcl-tk` from HomeBrew.
+
+```
+./configure --prefix=/usr/local/opt2/tcl-tk  
+make
+make install
+```
+
+## Build Tk for X11
+
+#### Download Tk from https://prdownloads.sourceforge.net/tcl/tk8.6.10-src.tar.gz
+
+```bash
+./configure --prefix=/usr/local/opt2/tcl-tk \
+--with-tcl=/usr/local/opt2/tcl-tk/lib --with-x \
+--x-includes=/opt/X11/include --x-libraries=/opt/X11/lib  
+make
+make install
+```
+
+## Build magic
+
+We need to provide this `tcl-tk` and suppress compilation errors.
+
+```bash
+./configure --with-tcl=/usr/local/opt2/tcl-tk/lib \
+--with-tk=/usr/local/opt2/tcl-tk/lib \
+--x-includes=/opt/X11/include \
+--x-libraries=/opt/X11/lib \
+CFLAGS=-Wno-error=implicit-function-declaration
+make
+make install
+```
+----
+</details>
+
+--- 
+
+<img src="assets/2021-12-22-23-09-28.png" width="100">
+
+## Finished installing? Here's how to use `Magic`
+---
+### [Magic User's Guide](http://opencircuitdesign.com/magic/)
+---
 
 
-2. Compilation and Installation:
----------------------------------
-   See the file "INSTALL" in this directory, or "INSTALL_MacOS.md" for MacOS.
 
-3. Version 8.3 Release Notes:
+----
----------------------------------
+# Documenation and usefull links
+### Primary documentation is on [opencircuitdesign.com](http://opencircuitdesign.com/magic/)
 
+---
+## Install
+### information on obtaining, compiling, and installing the tool from source
+[Magic Compile and Install Information Page](http://opencircuitdesign.com/magic/install.html)
+---
+## Download Bundle
+##### Note: this bundle is often out of date, its recommended to compile from source. see **[Install](## Install)**
+   [Magic Download Page](http://opencircuitdesign.com/magic/download.html)
+
+## How to use magic
+#### basic usage information including a complete on-line
+command reference
+
+### [Magic User's Guide](http://opencircuitdesign.com/magic/)
+
+## Magic Technology Files
+#### for essential documentation on how to understand, edit, or write technology files for Magic
+[Magic Technology Files](http://opencircuitdesign.com/magic/)
+
+## Code History
+### detailed comments on all code changes
+### [Magic Code Revision History](http://opencircuitdesign.com/magic/history.html)
+
+## Magic Documentation Page
+#### for miscellaneous papers and historical documentation converted to HTML format.
+### [Magic Documentation Page](http://opencircuitdesign.com/magic/magic_docs.html)
+
+
+## Old documentation
+#### Mainly historical interest only, now available through the [WayBack machine here](https://web.archive.org/web/20051217204815/http://www.research.compaq.com:80/wrl/projects/magic/magic.html)
+---
+
+# Maintainer(s)
+### The current distribution version of magic is maintained by 
+![](assets/2021-12-22-23-11-27.png)
+
+`Tim Edwards`
+
+ <tim@opencircuitdesign.com>  
+### Please let me know of any problems/bugs you find through the github Issues tracker`
+---
+### Additional information from developer `Rajit Manohar`:
+### [csl.yale.edu/~rajit/magic/](https://csl.yale.edu/~rajit/magic/)
+
+
+
+# Release Notes:
+
+<details>
+  <summary>Version 8.3 Release Notes:</summary>
 During the course of version 8.2, magic moved to a git-oriented
 development.  There are no longer "stable" and "distribution"
 versions.  There is only the git repo with various development
@@ -50,9 +304,9 @@
 for cells, and speeds up a number of methods, such as extraction,
 by a factor of 3 to 5 or so, depending on the amount of hierarchy
 in the design.
-
+</details>
-4. Version 8.2 Release Notes:
+<details>
----------------------------------
+<summary>Version 8.2 Release Notes:</summary>
 
 As of the release of version 8.2, Version 8.1 is now the new stable
 distribution, and 8.2 is the development distribution.  First
@@ -79,9 +333,10 @@
 Corrected the "extresist" method for non-FET devices, although it
 continues to need fundamental work to remove its dependence on the
 ".sim" format files.
+</details>
+<details>
+<summary>Version 8.1 Release Notes:</summary>
 
-5. Version 8.1 Release Notes:
----------------------------------
 
 As of the release of version 8.1, Version 8.0 is now the new stable
 distribution, and 8.1 is the development distribution.
@@ -93,9 +348,10 @@
    the hack handling of nMOS bulk connections using a default
    name without any understanding of a substrate node and
    connectivity.
+</details>
+<details>
+<summary>Version 8.0 Release Notes:</summary>
 
-6. Version 8.0 Release Notes:
----------------------------------
 
 As of the release of version 8.0, Version 7.5 is now the new stable
 distribution, and 8.0 is the development distribution.
@@ -121,9 +377,9 @@
 
 7) New extraction method "msubcircuit" with methods for specifying
    parameter names for source/drain area and perimeter.
-
+</details>
-7. Version 7.5 Release Notes:
+<details>
----------------------------------
+<summary>Version 7.5 Release Notes:</summary>
 
 Version 7.5 is the development branch.  Version 7.5.0 is the same as
 7.4.2, which is essentially the same as 7.3.123, plus some
@@ -176,9 +432,9 @@
    an intersection.
 
 See the online release notes for a more thorough list of features.
-
+</details>
-8. Version 7.4 Release Notes:
+<details>
----------------------------------
+<summary>Version 7.4 Release Notes:</summary>
 
 Version 7.4 is the new stable distribution version of magic.
 Apart from changes to the release notes, it is identical to
@@ -188,9 +444,9 @@
 development distribution, version 7.5.  Therefore there will
 not be a "What's new in 7.4" section, as there is not supposed
 to be anything new in version 7.4.
-
+</details>
-9. Version 7.3 Release Notes:
+<details>
----------------------------------
+<summary>Version 7.3 Release Notes:</summary>
 
 Magic release 7.3 incorporates a stacked contact model which is,
 for the most part, backwardly compatible with Magic releases
@@ -236,9 +492,9 @@
 27) Added executable "magicdnull" for streamlined batch-mode use
 28) New method for crash backups, including restore with "magic -r"
       29) A number of other technology file additions and enhancements
-
+</details>
-10. Version 7.2 Release Notes:
+<details>
----------------------------------
+<summary>Version 7.2 Release Notes:</summary>
 
 Magic release 7.2 incorporates the capability to run magic from the Tcl
 interpreter with graphics handled by Tk.  Instructions for compiling
@@ -294,9 +550,9 @@
    25) LEF and DEF format readers, LEF format writer.
    26) Improved techfile format with asterisk-notation and DRC
    "surround", "overhang", and "rect_only" statements.
-
+</details>
-11. Version 7.1 Release Notes:
+<details>
----------------------------------
+<summary>Version 7.1 Release Notes:</summary>
 
 Magic release 7.1 consolidates all known patches/features
 to magic version 6.5.x, and contains additional features that have
@@ -322,9 +578,9 @@
          - redid the make process and rewrote all Makefiles.
          - tons of other small things that hopefully make the build process
             nicer.
-
+</details>
-12. Releases prior to version 7:
+<details>
----------------------------------
+<summary>Releases prior to version 7:</summary>
 
 What's new in 6.5.2:
 --------------------
@@ -427,3 +683,23 @@
    information about the area and perimeter of diffusion and
    the bulk connection of the fets (written by Stefanos
    Sidiropoulos).
+</details>
+
+
+
+
+
+
+
+
+-----------------
+# Contributors
+
+[![](https://contrib.rocks/image?repo=RTimothyEdwards/magic)](https://github.com/RTimothyEdwards/magic/graphs/contributors)
+
+##### Made with [contributors-img](https://contrib.rocks).
+
+-----------------
+# License
+#### MIT © 1985, 1990 Regents of the University of California.
+[![License: BSD](https://img.shields.io/badge/License-BSD-yellow.svg)](https://opensource.org/licenses/MIT)