= How to install Magnolia = The Magnolia compiler is embedded in the Magnolia IDE, a collection of plugins for Eclipse. Eclipse runs on the Java virtual machine. The Magnolia compiler outputs C++ code by weaving together C++ backend code from the Magnolia library with compiled Magnolia source code. The Magnolia library is stored in an open subversion repository. The C++ code is compiled to executables using a C++ compiler under control of a ''make'' script. Thus all of these components need to be present for the Magnolia system to work. '''Note''': The Magnolia plugin is demanding and may easily be in conflict with other Eclipse plugins. You should therefore keep the Magnolia IDE separate from other Eclipse installations on your machine. == 1. Prepare your computer == === Install Java JDK 8 === Only Java 8 will work for Magnolia so make certain you have this, possibly in addition to any other Java version you may be using. * You need the full JDK (Java Development Kit), not just a JRE (Java Runtime Environment). * Make certain you choose a JDK 8 from summer 2017 or later due to certificate issues with some of the Eclipse plugins. * There are several choices for free downloads of JDK 8 (the first two of these appear to be obsolete): * [http://openjdk.java.net/ OpenJDK] an open source JDK, works nicely if available for your platform (provided for most Linux distributions); * [http://jdk.java.net Oracle's OpenJDK] production-ready open-source builds of the JDK from Oracle (limited range of platforms); * [http://www.oracle.com/technetwork/java/javase/downloads/index.html Oracle Java SE JDK] commercial JDK builds from Oracle (requires creating an account), free downloads for most platforms; As your system probably will have a more recent Java installed, you will need to tell Eclipse to use the Java 8 virtual machine by adding the path to the {{{-vm}}} option in the {{{eclipse.ini}}} file (see below). === Install C++ 2011 (or more recent) compiler === The Magnolia plugin contains a compiler from Magnolia to C++ 2011. These programs must be compiled with a 2011 (or newer) enabled C++ compiler, e.g., gnu g++ 4.8 or preferably newer, or clang++. Most systems come with a relatively up to date C++ compiler and make facility, otherwise you need to install one yourself. * On MacOSX terminal windows and compilers are part of the ''Xcode'' tool suite, available for free in the App Store (see  menu, on the upper left). * On Windows it may now be possible to use Magnolia with the native developer tools. Otherwise we recommend installing the [https://cygwin.com/install.html Cygwin] free, open-source gnu g++ and make utility. When using the downloader, be certain to activate the developer section and select the ''gcc-g++:GNU Compiler Collection'' and ''make: The GNU Version of the ‘make’ utility''. == 2. Install Eclipse for Magnolia == Create the directory ''magnolia'' (or whatever name you prefer) for storing Eclipse and your Magnolia workspace. This is recommended, but not necessary. There are several alternatives for downloading Eclipse. We recommend downloading an Eclipse package (do '''not''' use the Eclipse installer): * [https://www.eclipse.org/downloads/packages/release/oxygen/3a Eclipse Oxygen Package] '''recommended''' release. {{{#!comment Choose ''Eclipse IDE for C/C++ Developers'' if you just want to develop Magnolia code, or ''Eclipse for RCP and RAP Developers'' if you want to enhance the Magnolia plugin. }}} Choose ''Eclipse IDE for C/C++ Developers''. Depending on your operating system you may now have an {{{eclipse-cpp-oxygen-*.zip}}}, an {{{eclipse-cpp-oxygen-*.dmg}}}, or an {{{eclipse-cpp-oxygen-*.tar.gz}}} file. Unpack it, and install the software in the directory ''magnolia'' as planned. If you downloaded a tar file on Linux/BSD/Unix/MacOSX go to a terminal and move to the directory ''magnolia''. In the terminal unpack Eclipse by writing {{{tar xzfp [name of downloaded package]}}}. After installation you may optionally remove the installation files. === Edit the file ''eclipse.ini'' === NB! On current MacOS you need to start Eclipse (and immediately quit it) before editing the "eclipse.ini" file. Use something like {{{open -a Eclipse*.app --args -vm jdk8path}}} (where {{{jdk8path}}} is the path to the JDK 8 tools, see below). The file ''eclipse.ini'' is a normal text file which is somewhere in the newly unpackaged directory. At the top insert the lines {{{ -vm }}} The path to JDK 8 {{{jdk8path}}} may be something like {{{C:\Program Files\Java\jdk1.8.0_144\bin}}} on Windows, {{{/System/Library/Frameworks/JavaVM.framework/Versions/A/Commands}}} on MacOS, or {{{/opt/java-jdk-1.8.0.102/bin}}} on Linux. Then increase the heap size to 8g (or as much as you can afford given your machine's memory) by modifying the {{{-Xmx1024m}}} line in the ''eclipse.ini'' file: {{{ -Xmx8g }}} Memory size is given in Megabyte (m) or Gigabyte (g). Magnolia might work without adjusting the heap size, but if you get stack overflows, this will normally fix it. [https://wiki.eclipse.org/Eclipse.ini See here for more information about the ''eclipse.ini'' settings]. == 3. Prepare Eclipse by adding plugins and configuring them == Start Eclipse. On Linux/BSD/Unix you can do this by writing in a terminal {{{ ~/magnolia/eclipse/eclipse }}} On MacOSX you should write {{{ open ~/magnolia/Eclipse.app }}} or double-click on the Eclipse icon from an appropriately placed Finder window. A similar action is used in Windows. Eclipse will ask you for a workspace folder. Move to the magnolia directory, place the folder there, and select to use this as the default. === General Plugin Installation Instructions === We will now install several new plugins for Eclipse. You do not need to restart Eclipse until you have installed all the plugins. To install or update a plugin, go to ''Help → Install New Software''. Enter the URL of the update site (provided below) in the ''Work with'' field. Make certain the ''Contact all update sites'' option enabled (it is on by default. Contacting all sites takes some extra time, but it saves quite a few headaches chasing dependencies). Select the desired plugin features, press ''Next'', say OK to the license, press ''Next'' a few more times, then say OK to installing unsigned software. You can say no to restarting if you plan to install more plugins right away. **Installation tip:** If your network connection is bad, or some of the servers are down, you'll need to restart Eclipse in order to try again. === Install Rascal and Magnolia plugins (absolutely necessary!) === Install Rascal and Magnolia plugins by adding the following update site to Eclipse: https://bldl.ii.uib.no/magnolia/eclipse-plugin/ There are two packages to choose. Select and install both. Installing Rascal may give some warnings/errors about package conflicts. In the "Install Remediation Page" select "Update my installation to be compatible with the items being installed" (second option). This will typically remove {{{C/C++ Remote Launch}}} and {{{TM Terminal}}} package from Eclipse and will normally be sufficient to get Rascal to install. You do not need to restart Eclipse yet. === Install Subclipse (for accessing Subversion file stores with the Magnolia Libarary) === Install "Subclipse" from the ''Eclipse Marketplace…'' in the ''Help'' menu. Untick {{{JavaHL}}} in the list of packages that appear. {{{#!comment If possible, you should choose a Subclipse version for compatibility with your system's subversion. On Linux/BSD/Unix/MacOSX you can find the subversion version by typing the command line {{{svn --version}}} in the terminal window. }}} {{{#!comment You do not need to restart Eclipse yet. === Install Eclipse C/C++ development tool - CDT (recommended) === You can skip this step if you installed ''Eclipse IDE for C/C++ Developers''. Install CDT (search for ''C++ IDE CDT'') from the ''Eclipse Marketplace…'' in the ''Help'' menu. }}} === Restart Eclipse === Restarting Eclipse now will activate all your installed plugins. {{{#!comment === Configuring Subversion (recommended) === To avoid lots of SVN related error messages, you should go to ''Window → Preferences'' (MacOSX: ''Eclipse → Preferences'' or press keys ''Cmd-,''), expand ''Team'' in the left-hand side menu, select ''SVN'', and then select the SVNKit client library instead of the default JavaHL: [[Image(sophus.png)]] }}} === Emacs Keys (optional) === If you're an Emacs follower, you can choose Emacs-like keybindings by going to ''Window → Preferences → General → Keys'', and then selecting ''Emacs'' as the scheme. {{{#!comment (You'll need to do this in the second-level Eclipse as well, if you use that.) }}} If you have a Norwegian / Scandinavian keyboard, you may also want to bind Undo to Ctrl+-. === Add a Magnolia Eclipse button to your desktop (optional) === You can optionally add a Magnolia Eclipse button to your desktop or menu (consult your desktop environment for how to do this). == 4. Compiling and Running Magnolia Programs == The Magnolia plugin contains a compiler from Magnolia to C++ 2011. Download the Magnolia basic library and get started. Go to menu ''File → New → Other…'', choose ''SVN → Checkout Projects from SVN'', create a new repository location, and fill in the Location https://svn.ii.uib.no/r/magnolia/trunk/magnolia-basic-library Then download all of it to the default Eclipse workspace location. The Magnolia compiler automatically starts when the project has been downloaded. The compiler is slow, so this will take about half an hour. You can track the process in the Eclipse progress view, ''Window → Show View → Progress'', though this information is often misleading. After Eclipse is finished generating the C++ code, you are ready to compile the source and run a few tests. On Linux/BSD/Unix/MacOSX open a terminal window {{{ cd ~/magnolia/workspace/magnolia-basic-library/cxx ./make -j4 }}} (The ''-j4'' option runs 4 compilers in parallel on the generated code, and is only useful on a multicore system with more than 4 cores. Change the number, or remove the option, as you see fit.) The make command will create several executables (also a time consuming process) and run some tests. You are now ready to follow the tutorial examples in folder {{{TutorialExamples}}} and start coding in Magnolia. To execute the ''hello world!'' program in tutorial 0, simply type (in the terminal, at the cxx location) {{{ TutorialExamples/Tutorial0Cxx/welcomeCxx hello }}} Whenever you add or save a modified Magnolia file, Eclipse will automatically recompile the part of the Magnolia system that depends on the modified file. When recompilation is finished, you can run the ''make'' file as above to create an executable and test your programs. When you are ready for serious Magnolia development, you should switch off automatic compilation: Untick ''Project → Build Automatically''. You can now compile Magnolia files by clicking the ''build package'' button (leftmost of the three Magnolia buttons on the top of your Eclipse Window). Clicking this button will also do a complete type checking of your current file, otherwise hovering over a module (signature, concept, implementation, satisfaction, program) name will type check and list the declarations within that module. You need to save the file before hovering/building will take effect. Happy coding the Magnolia way!