1.4.2 Use GUI to port and build Projects

Last modified by Tilal Ahmad on 2019/02/04 05:20

Overview

“csPorter for C++ GUI” application provides Graphical User Interface (GUI) to a command-line application csPorter for C++. The “csPorter for C++ GUI” application’s executable CsToCppPorter.GUI.exe is located in bin/gui subdirectory of “CsPorter for C++” installation directory.

"csPorter for C++ GUI" provides an easy and convenient way to perform typical operations when porting C# projects to C++ and building them afterwards (by using Cmake and corresponding compiler). Though one can use command-line application "csPorter for C++" directly, it is more suitable for automation (e.g. for scripting in continuous integration environments), while window-based "csPorter for C++ GUI" provides more flexibility and control over the porting process when performing porting manually.

Here is a screenshot of the csPorter for C++ GUI application’s main – and the only – window:

csPorter_GUI.PNG

The Main Menu bar located in the top row of the application’s widow provides access to all functions supported by the application – porting, building, saving/loading a workspace etc.

Below the Main Menu are located buttons and combo boxes that provide access to and control over the most essential functionality of the application – porting, generating project or makefile from ported source code, and building the ported C++ project. The buttons in this area serve as shortcuts to the corresponding subitems of the Action menu item of the Main Menu.

Next goes the middle area of the window, which is divided into two logical subareas – left and right. The left area is associated with the C# project to be ported. It contains controls that allow one to specify path to the Porter configuration file and path to the C# project to be ported. Also it contains a tree view control that displays the content and structure of the specified C# project. The right subarea of the window’s middle area is associated with the output directory, where porter will put files generated during poring. This subarea contains an input box that allows one to specify path to the output directory and a tree view control that displays the contents of the specified directory.

The bottom area of the window contains a text box labelled "Output" to which the log of the activity in the application is printed including the output of any external applications executed by "csPorter for C++ GUI" (e.g. “csPorter for C++” or Cmake).

Porting a C# project

Before a C# project can be ported, some information needs to be passed to "csPorter for C++ GUI" application: path to the .csproj file of the C# project to port, path to the output directory where Porter will put all generated files including C++ source files and optionally path to Porter configuration file containing Porter configuration options and settings can be specified.

Specifying a C# project to port

Path to the .csproj file of the C# project to be ported is obligatory and must be specified in the text box containing corresponding prompt: “Enter path to C# project to port”. The path can be specified by typing it right into the text box or by choosing it in a filesystem tree window that pops-up when button labeled “…” located beside the input box is clicked. When the path to the .csproj file is specified and if it is correct, the content and the structure of the specified C# project is displayed in a tree-view control below the corresponding input box.

Specifying a path to the configuration file

Path to the Porter configuration file is optional. It can be specified in the input box containing the following prompt: “Enter path to configuration file”. The path can be typed into the input box or selected from a file system tree window that opens when button labeled “...” located to the right from the input box is clicked. In order to instruct the "csPorter to C++ GUI" application to use default configuration, checkbox labeled “use default” located to the right from the input box has to be set, in which case the input box becomes disabled and the value specified there - if any - is ignored by the application.

Specifying the output directory

The last thing Porter needs to know to perform porting is the output directory to put the generated files - result of poring - into. The path to the directory is obligatory and must be specified in the input box located on the right half of the window and containing the prompt “Enter path to the output directory”. The path can be typed into the input box or chosen in a filesystem tree-view window that is opened by clicking on a button labeled “…” to the right from the input box. When the path to the output directory is specified and if it is correct, the content of the specified directory is displayed in the tree-view control below the corresponding input box.

Note that if the specified path to the output directory is correct and the corresponding directory contains file named CMakeLists.txt, "csPorter for C++ GUI" assumes that this directory contains C++ and Cmake configuration files generated by Porter and buttons labeled “Generate project/makefile” and “Build” and their corresponding items of Actions submenu item of Main Menu become enabled. The application does not care if the files located in the output directory were generated during current session or anytime in the past or maybe even not by "csPorter for C++ GUI". If the application finds some Cmake configuration files in the output directory, it enables functionality to work with them by enabling corresponding buttons and menu items.

Porting

When all necessary parameters are specified, porting can be performed. Porting action is initiated by clicking button named “Port” or a Main Menu item Action->”Port project”. If one or more necessary parameters are not specified, the porting is not initiated and the problem input boxes are marked with red border, suggesting that they must be filled.

When porting is running, all other actions are not allowed to be initiated, therefore the corresponding buttons and menu items become disabled until porting finishes.

While porting action is running, the log is written to the text box labelled “Output”. When porting finishes, the log and result of the action can be seen in the “Output” textbox.

Depending on the size and complexity of the C# project being ported, the running time of the poring action may vary in quite wide range – from just a couple of seconds to tens of seconds and minutes. Main Menu item Action->Cancel will abort the running action.

When porting finishes successfully, the output directory contains the results of porting - C++ source files and Cmake configuration files generated by Porter.

Configuring and building C++ project

Besides porting a C# project, "csPorter for C++ GUI" provides means to configure and build the resulting C++ project using Cmake. This functionality requires Cmake to be installed in the system and path to cmake.exe to be present in PATH environment variable.

Specifying the build system and configuration

Two combo boxes to the right from button labeled “Port” allow to specify a build system to build C++ project with and configuration of the C++ project to build. The specified build system and configuration are both used by “Generate project/makefile” and “Build” actions. And both these values are ignored during porting.

Though "csPorter for C++ GUI" generates C++ source code and Cmake configuration files that allow targeting Linux build systems, "csPorter for C++ GUI" does not provide means to do that for one reason - "csPorter for C++ GUI" is a Windows application while configuration and building for Linux has to be done on Linux system. Thus the build system combo box contains only those build systems, which are available on Windows – Visual Studio

Generating project/makefile

Depending on the specified build system the ported C++ project is configured for, Cmake will generate either a Visual Studio project file (when configuring for Visual Studio build system). The button labeled “Generate project/makefile” initiates configuration process by invoking Cmake with the proper parameters. The output produced by Cmake and the result of the operation is printed to and can be seen in the Output text box.

Building ported C++ project

After the ported C++ project is configured for particular build system, it can be built with that build system. Button labeled “Build” initiates the corresponding action. Building is perform using Cmake and assumes that all necessary components of the specified build system are installed. The output produced by Cmake and the result of the operation is printed to the Output text box.

Porting C# project and configuring and building C++ project with a single click

Main Menu item "Action > Whole workspace sequence" is equivalent to clicking buttons “Port”, “Generate project/makefile” and “Bulid” one by one.

Cancelling actions

Main Menu item "Action > Cancel" aborts the running action.

When any action is in progress (including workspace loading or saving, project porting, configuring or building, etc.), you can't run other actions, change workspace parameters or close the program window.

Workspace management

Workspace is a set of parameters specified by the user in the "csPorter for C++ GUI" application's window, which includes:

  • Path to the .csproj file that represents the C# project to port
  • Path to the Porter configuration file
  • The state of  the “use default” checkbox
  • Path to the output directory
  • Target C++ build system
  • Target C++ project configuration

Once specified these values can be conveniently stored to a file and then later loaded back.

Creating a workspace

The new workspace is created implicitly everytime "csPorter for C++ GUI" application is started. There is no need (and no way) to create it manually.

Saving workspace

Main Menu item "File > Save workspace as..." opens a window in which name and location of the file to which the workspace should be saved can be specified. When a workspace is saved to a particular file, it is associated with that file. Main Menu item "File > Save workspace" saves current workspace to the file it is associated with, overwriting the file. If the current workspace is not associated with any file yet, “File > Save workspace” Main Menu item behaves just like “File > Save workspace as…”.

Opening existing workspace

Main Menu item "File > Open workspace..." opens a window where one can choose a workspace file. Once a correct file is chosen, all values stored in it are loaded and corresponding controls on the main window are filled with the loaded values.

Getting help

Use "Help > Online help" menu to get to online help page.

Use "Help > About..." menu to get basic program and version information.

Tools location

"csPorer for C++ GUI" always uses Porter and Library located in the same installation pack. "csPorter for C++ GUI" cannot be used with different Porter or Library version.

To configure and build ported C++ projects, Cmake must be installed and path to cmake.exe must be added to the PATH environment variable. To check if this is the case, run Command line, enter "cmake /?" command and press Enter. If Cmake is installed propertly, you should be geting Cmake help output.

Also, to build ported C++ projects, build systems must be installed on the system. If you're building projects from "csPorter for C++ GUI", Cmake is responsible for detecting build systems for you.

If you're configuring and/or building your ported C++ project manually, use ASPOSE_ROOT Cmake variable to specify path to installation of "csPorter for C++" you're using. Make sure the installation is the same you use Porter from. Typical Cmake command line should look like below:

cmake -G "Visual Studio 15 2017" -DASPOSE_ROOT="path\to\csporter\installation" path\to\ported\project
Tags:
Created by Tilal Ahmad on 2018/09/29 14:41