h1. Installing AMC development version on macOS

This is a translation of the French entry wiki. First translation was done by Pieter Van den Hombergh.

_(This installation - AMC version 1.3.0 revision 1968:8a1ee4d93e39 11/28/2016 - was tested with_

* _macOS 10.12.1 (Xcode 8.2, MacPorts 2.3.5)._

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.

In previous versions of this note, the source code of all necessary files were shown. As these sources are provided in the associated archive and not to burden the instructions, source code no longer appear in the note.

It is possible to install the "1.1.2 pre-compiled version":http://project.auto-multiple-choice.net/projects/auto-multiple-choice/wiki/Installation_d'AMC_sous_OS_X , but you would miss the newest developments happening in this active project. You can also install from the source, directly from the development  repository. This will give you the bleeding edge version.

For the moment, this installation guide is quite technical and has only been tested on macOS 10.11.5, 10.10.5 and 10.9.5 with the corresponding latest version of Xcode. You will need "MacPorts":http://www.macports.org, a little understanding of the dependencies between different tools (Subversion, MacPorts, PERL, X11, port ...) and the macOS architecture. You should also have administrative rights on the computer. This manual is therefore unfortunately not for everyone.

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

The requirements are the same as the installation of version 1.1.2 AMC. 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.

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. 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.

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* : 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. DejaVu font family

DejaVu fonts are used for japanese documentation generation.

 Ces polices sont utilisées pour la génération des documentations en japonais. 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.

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 hierarchy MacPorts. 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 OS X 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 only AMC port description. Archive for macOS 10.11 and 10.12 includes an adaptation of ports @gcc5@ and @pdftk@ to make them working under these versions of macOS.

Download and uncompress this archive then move the "@macports@" folder inside the previously created 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.

h4. Excerpt for @x11/auto-multiple-choice-devel/Portfile@

<pre title="x11/auto-multiple-choice-devel/Portfile"># -*- coding: utf-8; mode: tcl; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- vim:fenc=utf-8:ft=tcl:et:sw=4:ts=4:sts=4

# $Id$

PortSystem              1.0

PortGroup               bitbucket 1.0

PortGroup               perl5 1.0

set bitbucket_commit    "8a1ee4d93e39"

set amc_revision        "1968"

#1968:8a1ee4d93e39

bitbucket.setup         auto-multiple-choice auto-multiple-choice ${bitbucket_commit}

name                    auto-multiple-choice-devel

version                 1.3.${amc_revision}

categories              x11 tex education

platforms               darwin

license                 GPL-2+

maintainers             laposte.fr:joel.brogniart,openmaintainer

description             Auto Multiple Choice - Multiple Choice Papers Management

long_description        Utility to manage multiple choice questionnaires, \

                        with optionally mixed questions and answers. \

                        AMC provides automatic marking from papers' scans. \

                        Annotated papers are produced. Marks can be exported \

                        as an OpenOffice.org sheet file.

homepage                http://home.gna.org/auto-qcm

checksums               rmd160  ee0cad1b92745f0bd4e8c13ade0cd867dd6e5558 \

                        sha256  12bdca73bc7b15253f5eabe61ac69131bb3f1bbd174a581ec1c2bec54d426dbe

depends_build-append    \

                        port:dblatex \

                        port:p${perl5.major}-xml-libxml

</pre>

h2. Installing AMC

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

<pre>cd ~/nix/macports

portindex</pre>

*Warning*: standard and development of AMC versions can't be installed simultaneously. If a standard version was previously installed, you must uninstall it before installing the development version.

<pre>sudo port uninstall auto-multiple-choice</pre>

The installation of the development version of AMC can be launched. AMC depends on many other ports. The calculation and verification of all dependencies generates the opening of a large number of files that can cause installation failure. To avoid a failure, it is best to proceed in stages. First install the @pdftk@ port.

<pre>sudo port install pdftk</pre>

Then install @pdflatex@ port.

<pre>sudo port install pdflatex</pre>

Finally install AMC.

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

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

h2. Using AMC

You can start from the terminal or from XQuartz.

h3. In the Terminal

<pre>auto-multiple-choice</pre>

This command will launch XQuartz and AMC application.

h3. In XQuartz

Start XQuartz application.

!xquartz.png!

We can immediately set XQuartz to facilitate the launch of AMC. Open the @Applications > Customize...@ menu.

!xquartz-menu-applications-personnaliser.png!

In the Personalization window, click the button @Add an entry@.

!xquartz-fenetre-personnaliser-menu-applications.png!

Set "@Auto Multiple Choice@" in the @Name@ column and "@auto-multiple-choice@" in the @Command@ column of the new menu item.

!xquartz-fenetre-personnaliser-menu-applications-2.png!

Close the Customize window, then select the @Applications > Auto Multiple Choice@ menu.

!xquartz-menu-applications-amc.png!

AMC window should appear.

!auto-multiple-choice-window.png!

Auto-multiple-choice is now ready to work.

h2. Links

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

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

* 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>.