
\documentclass[11pt]{article}
\setlength{\textwidth}{5.5in}
%\setlength{\evensidemargin}{-0.5in}
\usepackage{TRmydraft} % title page report
\usepackage{wmff} % algorithm
\usepackage{yprob} % algorithm listing, code, report exercises

\usepackage{graphicx}
\usepackage{float}
\usepackage{url}

\pagestyle{myheadings}
\markright{Using Shell Commands and CodeBlocks\hfill}

\begin{document}

\reptitle{\bf OOSimL Simulation Models}
\author{Dr. Jos\'e M. Garrido}



\subtitle{\bf On Windows and Linux}
\subsubtitle{\bf Using a Terminal (or Command) Window and Codeblocks}


\authoraffil{Department of Computer Science} 
 
%
%\halftitlepage
%

\titlepage

\mdraft
%\maketitle
%\newpage
%\tableofcontents
%\newpage





\section{Introduction}


Software can be developed using directly text operating systems shell commands with an appropriate editor, or an Integrated Development Environment (IDE). There are several IDEs that help developing  programs written in C, C++, Fortran, and other programming languages.  Eclipse is one of the most complete and powerful tools, it is mainly useful for Java programs and in general, it can be very slow. For C++, C, and Fortran programs, Codeblocks and CodeLite are faster, lighter, and more convenient tools to use.  

This document briefly explains implementing OOSimL simulation models and C++ programs using:

 \begin{itemize}
    \item
   The text Linux and Windows commands necessary that can be used on a Terminal or Command window.
 \item
   CodeBlocks on Linux and Windows 

\end{itemize}

Note that the OOSimLC compiler/translator, and the simulation library were compiled with GNU C++ compiler tools.

\section{Downloading and Installing the OOSimLC Software}

The preliminary step required is the installation of the the OOSimL translator, the  simulation library, and the corresponding header files in the computer system running Linux or Windows. 

\begin{enumerate}
\item
On Linux, download the archive file {\tt oosimlc.tar.gz} from the following  web page and extract  all files from archive. 
 
\medskip
 \url{ksuweb.kennesaw.edu/~jgarrido/oosimlc} 
\medskip

\item
Select the executable file of the OOSimL compiler/translator, {\tt oosimlc.out} for 32-bit Linux or {\tt oosimlc64.out} for 64-bit Linux depending on the version of Linux your computer (32-bit or 64-bit).
\item
Rename {\tt oosimlc64.out} to {\tt oosimlc.out} in a 64-bit Linux. 
\item
The compiler file ({\tt oosimlc.out}), the simulation library ({\tt liboosimlc.a}), the {\tt compl} script file and the header files (including {\tt oosiml.h})  must be stored on a folder such as \url{~/oosimlcdir}.

\item
The subdirectory {\tt models}, contains some pre-defined simulation models and have the {\tt osl} extension.
\end{enumerate}

On Windows, the name of the archive is {\tt oosimlc.zip}. The name of the OOSimL translator is {\tt oosimlc.exe}. The simulation library and the header files have the same names as mentioned for Linux.


 \section{Using a Terminal or Command Window}
 \subsection{Using Linux}
 
 \begin{enumerate}
 \item
On Linux, open a Terminal window and change to the directory where the OOSimLC software is stored. Type the command:

{\tt cd oosimlcdir}
\medskip

\item
Verify that the compiler/translator, the simulation library, and the header files are in the directory. Type {\tt ls}, and this will list all files and subdirectories in the current directory.

\item
The subdirectory {\tt models} stores all the OOSimLC simulation models. These have an {\tt .osl} extension. Change to the subdirectory by typing {\tt cd models}, then type {\tt ls} to verify that all simulation models from the downloaded archive are present.

\item
To compile the simulation model in file {\tt Carwash.osl}, type the following command:

\medskip
{\tt ../oosimlc.out Carwash.osl}
\medskip

This is equivalent to the command:

\medskip
\url{~/oosimlcdir/oosimlc.out} {\tt  Carwash.osl}
\medskip

\item
Verify that the new file generated, {\tt Carwash.cpp}, is in the current directory. Type {\tt ls -lt}, and this will list all files and subdirectories in the current directory ordered by date and time.

\item 
Compile and link the generated file ({\tt Carwash.cpp}) with the GNU C++ compiler tool set. To compile and link file {\tt Carwash.cpp}, type the following command:

{\tt g++ Carwash.cpp  -I}  \url{~/oosimlcdir} {\tt  -L}  \url{~/oosimpcdir} {\tt  -loosimlc}

  {\tt  -lpthread   -lm}

\medskip

This will generate the executable file (by default) {\tt a.out}, which can be renamed with the {\tt mv} command.


\item
To run the executable file generated, type the command:

{\tt ./a.out}

When the simulation model runs, it produces two output text files, the statics file and the simulation trace file. For the  {\em Carwash} model, the files produced are: {\tt carwstatf.txt} and {\tt carwtrace.txt}.

\end{enumerate}


\subsection{Using Windows}

 \begin{enumerate}
 \item
On Windows, open a command window by typing {\tt cmd} on the Search option.  Change to the directory where the OOSimLC software is stored. Type the command:

{\tt cd oosimlcdir}
\medskip

\item
Verify that the compiler/translator, the simulation library, and the header files are in the directory. Type {\tt dir}, and this will list all files and subdirectories in the current directory.

\item
The subdirectory {\tt models} stores all the OOSimLC simulation models. These have an {\tt .osl} extension. Change to the subdirectory by typing {\tt cd models}, then type {\tt dir} to verify that all simulation models from the downloaded archive are present.

\item
To compile the simulation model in file {\tt Carwash.osl}, type the following command:

\medskip
\url{C:\oosimlcdir\oosimlc.exe} {\tt  Carwash.osl}
\medskip


\item
Verify that the new file generated, {\tt Carwash.cpp}, is in the current directory. Type {\tt dir /p/o-d}, and this will list all files and subdirectories in the current directory ordered by date and time.

\item 
Compile and link the generated file ({\tt Carwash.cpp}) with the GNU C++ compiler tool set. To compile and link file {\tt Carwash.cpp}, type the following command:

{\tt g++ Carwash.cpp  -I }  \url{C:\oosimlcdir} {\tt  -L  } \url{ C:\oosimpcdir}  {\tt  -loosimlc}

{\tt  -lpthread   -lm}

\medskip

This will generate the executable file (by default) {\tt a.exe}, which can be renamed with the {\tt ren} command.


\item
To run the executable file generated, type the command:

{\tt a.exe}

When the simulation model runs, it produces two output text files, the statics file and the simulation trace file. For the  {\em Carwash} model, the files produced are: {\tt carwstatf.txt} and {\tt carwtrace.txt}.

\end{enumerate}

 

\section{Using CodeBlocks IDE}

For a more detailed introduction to CodeBlocks, refer to various websites for CodeBlocks tutorial and documentation. 

The following sequence of steps involve the basic procedure for setting the appropriate options on Codeblocks for using the OOSimL translator then the remaining steps for editing C++ programs, compiling,  and linking with the simulation library in file {\tt liboosimlc.a}.
 

\subsection{Setting the Codeblocks Options}
\begin{enumerate}
\item
Start CodeBlocks and click on Create a new project.

\item 
Select Console Application and click the Go button, which is located on the upper right corner of the window. 

\item
On the Console Application window, click the Next button.  Select C++ language and click Next.
\item
Type the project title (name), e.g. {\em Carwash}. In this example, the project will be created in folder: \url{~/oosimlcdir/models}. Click the Next button.

On Windows, the project will be created in folder: \url{C:\oosimlcdir\models}

\item
Select GNU GCC Compiler and click the Finish button.

\item
On the top bar, click on the Settings menu then select Compiler. A dialog box appears: Global compiler settings. On the  tab group, activate the Other settings tab, and click the button Advanced options located on the lower right of the dialog box. 

\item
Click the Yes button when the box {\em Edit advanced compiler setting?} appears.
\item
On the new window that appears, click the '+' button and type {\tt osl} in the dialog box and click OK. This indicates that the OOSimL files have an {\em osl} extension.
\item
In the field: the Command line macro, type the command that will be used by CodeBlocks to execute the translator with a given OOSimL source file. For example:

  \url{~/oosimlcdir/oosimlc.out} {\tt \$file}

This assumes that the OOSimL translator  (executable file {\tt oosimlc.out}) is located in a folder named: \url{~/oosimlcdir}

On Windows, the Command line macro that will be used by CodeBlocks to execute the translator with a given OOSimL source file is:

  \url{C:\oosimlcdir\oosimlc.exe} {\tt \$file}

\item
In the Generated files field, type the generic file name generated that are C++ files: 

{\tt \$file\_name.cpp}

\item
Click the Ok button located on the bottom of the window.
\end{enumerate}

Codeblocks is now configured, for the current project, to recognize source files with an {\tt osl} extension for editing and to execute the OOSimL translator.

\subsection{Setting for Compiling and Running Simulation Models}

\subsubsection{Source Files}
\begin{enumerate}

\item
Activate the left pane of the screen (Management), click the Projects tab. Remove the  source file  {\tt main.c} by right-clicking on it and selecting Remove file from project. 
\item
A new source file can be created by selecting File menu, then New, and Empty file. Click Yes to add this empty to the project.  A new  dialog window appears, type the name of the file with its {\tt osl} extension. Now you can start editing this source file  and when finished, save the file.

\item
If one or more \underline{existing} source files are to be included in the project, select the Project menu  on the top bar, or right-click on the project name. Select Add files. Select the directory of the source to add to the project and select the OOSimL source file(s). Click Open.

\item
The source files are now under ‘Others’ and under the project name. Double-click on the desired source file to edit it further. The file now appears on the edit area of the screen.
\end{enumerate}

\subsubsection{Build Options}
\begin{enumerate}
\item
Right-click on the current project name, or activate the Project menu in the top bar, and select ‘Build options’. 

\item
 On the tab ‘Compiler settings’, check ‘Enable all compiler warnings’. 
\item
 On the tab ‘Linker settings’, click the ‘Add’ button to add a library to the project. Repeat to add all necessary object files and libraries. For  a typical simulation model, at the minimum, the file libraries are: {\tt liboosimlc.a},  {\tt pthread}, and  {\tt m}   (standard math library). 
 
 Note that the simulation library in file {\tt liboosimlc.a} is stored in a local directory, such as \url{~/oosimlcdir}. On Windows, the library would be stored in folder: \url{C:\oosimlcdir}.

\item
On the tab ‘Search directories’ and the tab 'Compiler',  add the search directory for header files required by the source program while compiling. Assume the header files required by the  programs are located in folder \url{~/oosimlcdir}.


\item
On the tab ‘Search directories’ and the tab 'Linker', add the search directory of the libraries if needed. On Linux (Ubuntu), the external libraries are always stored in standard system directories. The file of the simulation library {\em liboosimlc.a}  can be stored in any location, for example \url{~/oosimlcdir}. For this, click the Add button, then click (\ldots) and navigate to the appropriate directory.  

 
\end{enumerate}

\subsubsection{Building and Running the Project}
\begin{enumerate}

\item
Build the project, which translates the OOSimL source file, then compiles and links the C++ files in the project. On the top bar, select the Build menu and select the Build option. The Build log appears in the lower pane of the Codeblocks screen.



\item
To execute the program, select the Run option in the Build menu. A new screen appears with the results of the execution. After the program terminates execution, press the Enter key.



\item
On the top bar, activate the File menu and select Close project. Codeblocks creates several new subdirectories and the executable file in directory  \url{~/oosimlcdir/models/Carwash/bin/Debug}.

\end{enumerate}
\end{document}
