h1. Installing AMC development version on macOS with a non MacPorts LaTeX installation

This is a translation of the French entry wiki.

_(This installation - AMC version 1.3.0 revision commit:eb15ba78bfe7 4/11/2017 - was tested with_

* _macOS 10.12.4 (MacPorts 2.4.1, Xcode 8.3.1)._

Auto Multiple Choice (AMC) is a software to manage questionnaires and multiple choice exams. It allows, from the definition of the multiple choice questions to generate sheets of questionnaires. The question types can be one only choice, multiple choices, question, right/wrong answers etc. Once the completed questionnaires are digitized, AMC automatically corrects the questionnaires. This software runs in a graphical environment X Window System on Linux and macOS. Linux is used as the develop environment, so it probably runs best there. Your mileage may vary.

This document briefly describes the installation of Auto Multiple Choice using a LaTeX installation external to MacPorts. The version of AMC installed is a recent development version. The files and installation procedure described here are different from "Installing the AMC development version using the LaTeX installation from MacPorts":http://project.auto-multiple-choice.net/projects/auto-multiple-choice/wiki/Building_AMC_for_MAC_OSX. Apart from this aspect, AMC, works in the same way. Also only the installation part is described here.

The installation described here requires some knowledge of Unix tools, the use of command lines, an understanding of the "MacPorts":http://www.macports.org ports architecture, a little understanding of the dependencies between different tools (Subversion, MacPorts, PERL, X11, ports ...) and the macOS architecture. It is also necessary to have administrative rights on the computer.

For this installation you will create a local MacPort repository. In this repository you will add macports description for AMC and possibly files for additional ports. Once these files are installed, the installation of AMC can be started.

h2. Prerequisites

To work with the interface, AMC requires the graphical environment X Window System and X11, the Linux Libertine font, the DejaVu font family and the MacPorts installation system. A LaTeX installation (i.e. "MacTeX":http://www.tug.org/mactex/) should also be available.

h3. The X Window Environment

MacOS does not contain the standard X11 graphical environment. It is possible to fill this gap by installing XQuartz, an X Windows System environment running macOS. You can download the application on the XQuartz site. "XQuartz":http://xquartz.macosforge.org.

h3. Linux Libertine font

Linux Libertine font is a free font that covers code pages for Latin languages​​, Greek, Cyrillic languages​​, Hebrew, the International Phonetic Alphabet (and other). You need to download the package "OTF" on "LinuxLibertine.org":http://www.linuxlibertine.org site.

*Caution* : XQuartz does not recognize the fonts installed in the user's folder. You must install the fonts by moving them in the "@/Library/Fonts@" folder.

h3. DejaVu font family

DejaVu fonts are used for japanese documentation generation. You need to download the fonts on "dejavu-fonts.org":http://dejavu-fonts.org/wiki/Download site.

*Caution* : The current version of XQuartz (2.7.11) does not recognize the fonts installed in the user's folder. You must install the fonts by moving them in the "@/Library/Fonts@" folder.

h3. MacPorts

MacPorts is a system to build, install and manage open source software. You need to download the macOS Yosemite installation package on the site "MacPorts":http://www.macports.org and install MacPorts.

h2. MacPorts and non MacPorts LaTeX installation

To build AMC with a non MacPorts LaTeX installation you need several things.

First, MacPorts build tools must be able to access external LaTeX tools. For example, with the MacTeX 2016 installation, these tools are available in the "@/Library/TeX/texbin@" folder. MacPorts configuration must be changed so that this folder is included in the @path@ of MacPorts.

Caution, as explained in the "MacPorts documentation":https://guide.macports.org/chunked/internals.configuration-files.html, editing the MacPorts' @path@ can have unpredictable effects and consequences for others tools. It should be avoided.

Edit the "@/opt/local/etc/macports/macports.conf@" file to add the following line.

<pre>binpath               /opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin:/Library/TeX/texbin</pre>

If you use a tool other than MacTeX, you must replace the last part of the @path@ with the folder containing the binaries of your LaTeX tool.

The @dblatex@ tool should also be build for this external LaTeX installation.

h2. MacPorts installation (port) files

The MacPorts port file contains information that allows a program to be installed into the MacPorts system. It shows what tools are needed for installation and operation of the program and how to install the program. 

MacPorts contains "many ports":http://www.macports.org/ports.php but it does not contain a port describing the AMC installation from the source code of the program. So we have to create the file port for the development version of AMC.

To avoid conflicts with ports already described in MacPorts, new ports will be installed in the folders of the user who installs, instead of being installed in folders directly managed by MacPorts.

h3. Local MacPorts repository

For MacPorts to use a local folder, you must create that local folder.

<pre>mkdir -p ~/nix</pre>

You should then tell MacPorts to take the local folder into account, before considering the standard MacPorts' hierarchy. To do this you must edit the file "@/opt/local/etc/macports/sources.conf@" and add a URL to the local file before the URL of the repository @rsync@ MacPorts.

<pre>file:///Users/julesvernes/nix/macports

rsync://rsync.macports.org/release/tarballs/ports.tar [default]</pre>

h3. Port Files

Two archives containing the port files are available for download:

* for installation on macO 10.9 and 10.10 attachment:macports-10.10.zip,

* for installation on macOS 10.11 and 10.12 attachment:macports-10.12.zip.

First archive contains the description for the @auto-multiple-choice-devel@ port and an adaptation of the @dblatex@ port that works also with a non MacPorts LaTeX installation. Archive for macOS 10.11 and 10.12 also includes an adaptation of ports @gcc5@ and @pdftk@ to make them working under these versions of macOS.

Download and uncompress the archive then move the "@macports@" folder inside the previously created folder.

The ports are grouped by categories and the port file organization reflects this grouping. Each port is in a main category and has its own folder. The main category of AMC in MacPorts is X11, so the port folder for AMC will be inside an x11 folder.

!port-hierarchy.png!

Each directory must contain a port document named @Portfile@. This document is a text document containing a description for the MacPorts installation tool.

h2. Installing AMC

Once the port files set up, generate the index of the new port.

<pre>cd ~/nix/macports

portindex</pre>

Then, install the @dblatex@ port without its dependencies to a MacPorts' LaTeX installation.

<pre>sudo port install dblatex -latex</pre>

And finally, it is necessary to launch in the same way the installation of the development version of AMC.

<pre>sudo port install auto-multiple-choice-devel -latex</pre>

The installation may take a while. When it is complete and if there is no error, @Auto Multiple Choice@ is ready to be used.

h2. Links

* Auto Multiple Choice, "http://home.gna.org/auto-qcm/":http://home.gna.org/auto-qcm/.

* Auto Multiple Choice, "Installation sous macOS":http://project.auto-multiple-choice.net/projects/auto-multiple-choice/wiki/Installation_d'AMC_sous_OS_X_Mountain_Lion.

* Auto Multiple Choice, "development version installation on macOS":http://project.auto-multiple-choice.net/projects/auto-multiple-choice/wiki/Building_AMC_for_MAC_OSX.

* MacPorts, "http://www.macports.org":http://www.macports.org.

* MacPorts, "Local Portfile Repositories":http://guide.macports.org/#development.local-repositories.

* MacPorts, "How to create portfiles for CPAN Perl modules":https://trac.macports.org/wiki/howto/cpan2port.

* XQuartz, http://xquartz.macosforge.org</a>.