<commit_before>\part{Tutorials}

\chapter{Installation and Setup} 

This section describes the installation of mbeddr in detail, including
Java, MPS and the additional tools needed for visualization and verification. 

\greyboxnote{We are working on a all-in-one distribution that includes MPS and
mbeddr. Stay tuned.}

\section{Java} 

MPS is a Java application. So as the first step, you have to install a Java
Development Kit version 1.6.x. You can get it from here \\
\hspace*{5mm}\ic{http://www.oracle.com/technetwork/java/javase/downloads/index.html}
\\ 
Note that currently MPS does not run on JDK 1.7.


\section{JetBrains Meta Programming System (MPS)} 

The mbeddr system is based on JetBrains MPS, an open source language workbench
available from \ic{http://www.jetbrains.com/mps/}. MPS is available for Windows,
Mac and Linux, and we require the use of the 2.5.x version. Please make sure you
install MPS in a path that does not contains blanks in any of its directory or
file names (not even in the \ic{MPS 2.5} folder). This will simplify some of the
command line work you may want to do.

After installing MPS using the platform-specific installer, please open the
\ic{bin} folder and edit the \ic{mps.vmoptions}  or \ic{mps.exe.vmoptions} file
(depending on your platform). To make MPS run smoothly, the \ic{MaxPermSize}
setting should be increased to at least \ic{512m}. It should look like this
after the change:

\begin{lstlisting}
-client
-Xss1024k  
-ea
-Xmx1200m
-XX:MaxPermSize=512m
-XX:+HeapDumpOnOutOfMemoryError
-Dfile.encoding=UTF-8
\end{lstlisting}

\onwin On some 32bit Windows XP systems we had to reduce the \ic{-Xmx1200m}
setting to \ic{768m} to get it to work.



\section{GCC and make}

The mbeddr toolkit relies on \ic{gcc} and \ic{make} for compilation (unless you
use a different, target-specific build process). 

\onmac On the Mac, you should install XCode to get \ic{gcc}, \ic{gdb},
\ic{make} and the associated tools.

\onlin On Linux, these tools should be installed by default.


\onwin On Windows we recommend installing cygwin
     (\ic{http://www.cygwin.com/}), a Unix-like environment for Windows. When
selecting the packages to be installed, make sure \ic{gcc-core}, \ic{gdb} and
\ic{make} are included (both of them are in the \ic{Devel} subtree in the selection
dialog). The \ic{bin} directory of your cygwin installation has to be added to the system
\ic{PATH} variable; either globally, or in the script that starts up MPS (MPS
runs \ic{make}, so it has to be visible to MPS). On Windows, the \ic{mps.bat}
file in the MPS installation folder would have to be adapted like this:
 
\begin{lstlisting}
::rem mbeddr depends on Cygwin: gcc, make etc
::rem adapt the following to your cygwin bin path
set PATH=C:\ide\Cygwin\bin;%PATH%
\end{lstlisting}

\section{Graphviz}

MPS supports visualization via PlantUML
(\ic{http://plantuml.sourceforge.net}), directly embedded in MPS.
To use it, you have to install graphviz, which you can get from
\ic{http://graphviz.org}.
We use version 2.30. After the installation, you have to put the \ic{bin}
directory of graphviz into the path. Either globally, or by modifying the MPS
startup script in the same way as above:

\begin{lstlisting}
::rem mbeddr depends on graphviz dot
::rem adapt the following to your graphviz bin path
set PATH=C:\ide\graphviz2.30\bin;%PATH%
\end{lstlisting}

\onwin On Windows, you also have to have an environment variable
\ic{GRAPHVIZ\_DOT} that points to the \ic{dot.exe} file supplied with graphviz.

\section{mbeddr}

You can get the mbeddr code either via distributions or via the public github
repository.

\parhead{Installing the Distribution} We recommend installing the distribution,
because this is a much simpler process than working from the github sources. The
distribution can be downloaded from the \ic{mbeddr.com} website:

\vspace{-3mm}
\hspace{10mm} \ic{http://mbeddr.wordpress.com/getit/}
\vspace{-3mm}

The ZIP file you can get there contains this user guide as well as a set of
plugins for MPS. Please take all the folders inside the \ic{plugins} directory
in the ZIP file and copy them into the \ic{plugins} directory under
MPS\footnote{Note that there is also a \ic{plugin} (without the \ic{s})
directory under MPS!}. So, for example, after copying, there should be a
\ic{\$MPS\_DIR\$/plugins/mbeddr.core} directory.


\parhead{Installing From github} Here are the steps to get
mbeddr running from the github repository. You should only do this if you want
to stay at the bleeding edge of mbeddr development, and if you plan to
regularly update your local mbeddr, or if you plan to fork it. Otherwise, we
recommend you stay with the distribution discussed above. 


\begin{itemize}
  \item Clone the repository onto your local machine. The repository is at \\
  \ic{https://github.com/mbeddr/mbeddr.core}. 
  
  
  \item Rebuild all the languages. We provide a shell script for this purpose 
  (\ic{.bat} and \ic{.sh}) called \ic{rebuildLanguagesAfterCheckout}. 
  It is in the \ic{code/languages} directory. For this to work, you have to
  configure all \ic{build.properties} files to point to your MPS install dir and
  the mbeddr root dir (\onwin \textbf{You have to use forward shlashes as
  directory separators even on Windows!}). The easiest way to find all the places 
  where this has to be adapted is to search for all \ic{build.properties.example} under the mbeddr
  root mbeddr directory; remove the \ic{.example} and fill in the respective
  directories. Note also that the shell scripts rely on Apache ant. You have
  to install it (from \ic{http://ant.apache.org/}) on your machine and make sure
  that the \ic{ant} script is in your path.

  \item When running the above-mentioned script, you should have an internet
  connection because the script also downloads a few additional MPS plugins and
  installs them in the MPS \ic{plugins} directory. These include a support
  plugin for debugging as well as the plugins to support multiline and richtext
  editing. 

  \item We now have to make future application projects aware of the
  \ic{mbeddr.core} languages in the github checkout directory. Start MPS and go
  to the $File \rightarrow Settings$ (on the Mac it is under $MPS \rightarrow Preferences$) and select the $Global
  Libraries$ in the IDE settings. Create a library called \ic{mbeddr.core} that
  points to the \ic{code} directory of the unzipped mbeddr
  installation. The library must point to the \ic{code}<commit_msg>some additions to the user gudie<commit_after>\part{Tutorials}

\chapter{Installation and Setup} 

This section describes the installation of mbeddr in detail, including
Java, MPS and the additional tools needed for visualization and verification. 

\greyboxnote{We are working on a all-in-one distribution that includes MPS and
mbeddr. Stay tuned.}

\section{Java} 

MPS is a Java application. So as the first step, you have to install a Java
Development Kit version 1.6.x. You can get it from here \\
\hspace*{5mm}\ic{http://www.oracle.com/technetwork/java/javase/downloads/index.html}
\\ 
Note that currently MPS does not run on JDK 1.7.


\section{JetBrains Meta Programming System (MPS)} 

The mbeddr system is based on JetBrains MPS, an open source language workbench
available from \ic{http://www.jetbrains.com/mps/}. MPS is available for Windows,
Mac and Linux, and we require the use of the 2.5.x version. Please make sure you
install MPS in a path that does not contains blanks in any of its directory or
file names (not even in the \ic{MPS 2.5} folder). This will simplify some of the
command line work you may want to do.

After installing MPS using the platform-specific installer, please open the
\ic{bin} folder and edit the \ic{mps.vmoptions}  or \ic{mps.exe.vmoptions} file
(depending on your platform). To make MPS run smoothly, the \ic{MaxPermSize}
setting should be increased to at least \ic{512m}. It should look like this
after the change:

\begin{lstlisting}
-client
-Xss1024k  
-ea
-Xmx1200m
-XX:MaxPermSize=512m
-XX:+HeapDumpOnOutOfMemoryError
-Dfile.encoding=UTF-8
\end{lstlisting}

\onwin On some Windows systems we had to reduce the \ic{-Xmx1200m}
setting to \ic{768m} to get it to work. If MPS does not start with the error
message \emph{Could not create the VM}, then it is likely that this is the
problem.



\section{GCC and make}

The mbeddr toolkit relies on \ic{gcc} and \ic{make} for compilation (unless you
use a different, target-specific build process). 

\onmac On the Mac, you should install XCode to get \ic{gcc}, \ic{gdb},
\ic{make} and the associated tools.

\onlin On Linux, these tools should be installed by default.


\onwin On Windows we recommend installing cygwin
     (\ic{http://www.cygwin.com/}), a Unix-like environment for Windows. When
selecting the packages to be installed, make sure \ic{gcc-core}, \ic{gdb} and
\ic{make} are included (both of them are in the \ic{Devel} subtree in the selection
dialog). The \ic{bin} directory of your cygwin installation has to be added to the system
\ic{PATH} variable; either globally, or in the script that starts up MPS (MPS
runs \ic{make}, so it has to be visible to MPS). On Windows, the \ic{mps.bat}
file in the MPS installation folder would have to be adapted like this:
 
\begin{lstlisting}
::rem mbeddr depends on Cygwin: gcc, make etc
::rem adapt the following to your cygwin bin path
set PATH=C:\ide\Cygwin\bin;%PATH%
\end{lstlisting}

\section{Graphviz}

MPS supports visualization via PlantUML
(\ic{http://plantuml.sourceforge.net}), directly embedded in MPS.
To use it, you have to install graphviz, which you can get from
\ic{http://graphviz.org}.
We use version 2.30. After the installation, you have to put the \ic{bin}
directory of graphviz into the path. Either globally, or by modifying the MPS
startup script in the same way as above:

\begin{lstlisting}
::rem mbeddr depends on graphviz dot
::rem adapt the following to your graphviz bin path
set PATH=C:\ide\graphviz2.30\bin;%PATH%
\end{lstlisting}

\onwin On Windows, you also have to have an environment variable
\ic{GRAPHVIZ\_DOT} that points to the \ic{dot.exe} file supplied with graphviz.

\section{mbeddr}

You can get the mbeddr code either via distributions or via the public github
repository.

\parhead{Installing the Distribution} We recommend installing the distribution,
because this is a much simpler process than working from the github sources. The
distribution can be downloaded from the \ic{mbeddr.com} website:

\vspace{-3mm}
\hspace{10mm} \ic{http://mbeddr.wordpress.com/getit/}
\vspace{-3mm}

The ZIP file you can get there contains this user guide as well as a set of
plugins for MPS. Please take all the folders inside the \ic{plugins} directory
in the ZIP file and copy them into the \ic{plugins} directory under
MPS\footnote{Note that there is also a \ic{plugin} (without the \ic{s})
directory under MPS!}. So, for example, after copying, there should be a
\ic{\$MPS\_DIR\$/plugins/mbeddr.core} directory.


\parhead{Installing From github} Here are the steps to get
mbeddr running from the github repository. You should only do this if you want
to stay at the bleeding edge of mbeddr development, and if you plan to
regularly update your local mbeddr, or if you plan to fork it. Otherwise, we
recommend you stay with the distribution discussed above. 


\begin{itemize}
  \item Clone the repository onto your local machine. Our github repository is
  at \\ 
  \ic{https://github.com/mbeddr/mbeddr.core}, the repository URL to be
  used for cloning (for various prototocols) can be found at this URL.
  
  
  \item Rebuild all the languages. We provide a shell script for this purpose 
  (\ic{.bat} and \ic{.sh}) called \ic{rebuildLanguagesAfterCheckout}. 
  It is in the \ic{code/languages} directory. For this to work, you have to
  configure all \ic{build.properties} files to point to your MPS install dir and
  the mbeddr root dir (\onwin \textbf{You have to use forward shlashes as
  directory separators even on Windows!}). The easiest way to find all the places 
  where this has to be adapted is to search for all \ic{build.properties.example} under the mbeddr
  root mbeddr directory; remove the \ic{.example} and fill in the respective
  directories. Note also that the shell scripts rely on Apache ant. You have
  to install it (from \ic{http://ant.apache.org/}) on your machine and make sure
  that the \ic{ant} script is in your path.

  \item When running the above-mentioned script, you should have an internet
  connection because the script also downloads a few additional MPS plugins and
  installs them in the MPS \ic{plugins} directory. These include a support
  plugin for debugging as well as the plugins to support multiline and richtext
  editing. 

  \item We now have to make future application projects aware of the
  \ic{mbeddr.core} languages in the github checkout directory. Start MPS and go
  to the $File \rightarrow Settings$ (on the Mac it is under $MPS \rightarrow Preferences$) and select the $Global
  Libraries$ in the IDE settings. Create a library called \ic{mbeddr.core} that
  points to the \ic{code} directory of the unzipped mbeddr
  installation. The library must point to the \ic{code}
{'fraction_non_alphanumeric': 0.07610833711605386, 'fraction_numerical': 0.006354970494779845, 'mean_word_length': 4.07447216890595, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1685699', 'n_tokens_mistral': 4091, 'n_tokens_neox': 3885, 'n_words': 1897}