Building MiniGUI
Introduction
In general, embedded systems are special systems, and they have various requirements for different applications. For example, some systems require a basic graphics function to show images, but others may require a complete support for windowing and controls/widgets, even need to run a HTML5 web browser. Therefore, an embedded graphics system like MiniGUI must be tailorable.
For easy tailoring, MiniGUI provides a lot of compile-time macros to control the features of itself.
Generally, we can configure MiniGUI Core in the following aspects:
The operating system and the target board on which MiniGUI runs.
The MiniGUI runtime mode: MiniGUI-Threads, MiniGUI-Processes, or MiniGUI-Standalone.
The graphics engine and the input engine, as well as the options of these engines.
The font types supported.
The character sets supported.
The image file formats supported: MS Windows BMP, GIF, JPEG, and PNG.
The controls/widgets supported.
The look-and-feel renderers supported.
In this part, we will show you the compile-time configuration options of MiniGUI Core and the ways to configure it, in order that you can build a most suitable MiniGUI for your target devices. We will also show you how to build MiniGUI Core.
Configuration Header File
A file named mgconfig.h.in is located in the root directory of the source tree of MiniGUI Core. There are many C language macros listed in the file, but they are all undefined:
When a C compiler builds MiniGUI from source code, the MiniGUI source code will include a file named mgconfig.h. We can tailor MiniGUI by enabling some macros in mgconfig.h, while all macros supported are listed in mgconfig.h.in mentioned above.
Generally, we can copy mgconfig.h.in to mgconfig.h and modify mgconfig.h file manually in order to tailor MiniGUI.
In general, the content of mgconfig.h is as follow:
The code above is a snippet of a real mgconfig.h. Macro __VXWORKS__ is defined in this file and this macro will enable the support code for VxWorks in the MiniGUI source code. Macro _MGHAVE_CLIPBOARD is defined in this file too, it will enable the support for clipboard. Macro _MGIAL_AUTO is not defined (commented out) in this file and MiniGUI will not support the auto input engine.
mgconfig.h contains many MiniGUI macros (with prefix _MG). For detailed description of the MiniGUI macros, please refer to Compile-time Configuration.
It is very hard to modify mgconfig.h manually to meet your needs. Fortunately, with GNU GCC toolchain, you can use script configure to configure MiniGUI and generate mgconfig.h file automatically.
Note that you must rebuild MiniGUI if this header file is modified. Once MiniGUI is built, you should install the MiniGUI headers and mgconfig.h to your system's header file directory.
Configuring MiniGUI in GNU Environment
It’s known that we can conveniently maintain the program package using makefile. By using makefile, we can easily compile and install the function libraries, executable files, and header files into systems.
Although it is possible to organize a big project with makefile, it is not an easy job to create such a makefile manually. When we need to maintain a large-scale source code directory tree, the makefile maintenance work will increase greatly. Therefore, the Free Software Foundation's GNU project has developed the autoconf/automake tool for software projects which are based on C and C++ languages. Using this tool, we can automatically generate makefiles, and can check system configuration information, which helps enhancement the customizability of the software.
MiniGUI (MiniGUI Core, components, and sample packages) uses GNU automake/autoconf to organize source code. Therefore, if you use the GNU GCC toolchain for your target system, you may use MiniGUI’s automake/autoconf configuration script to configure MiniGUI and generate makefiles.
We know many embedded system vendors are now using the GNU GCC toolchain, which can easily run on a Linux system. Therefore, we can configure and build MiniGUI on a Linux system for your target system.
If you get MiniGUI source code from the tarball (libminigui-x.y.z.tar.gz), there will be a ready-to-use configure script. Run this script with some options, MiniGUI will be configured. Then, run make command to build MiniGUI:
If you fetch MiniGUI source code from a public Git repository, there is no such a ready-to-use configure script. Under this situation, you need to make sure have autoconf installed in your system, and run autogen.sh script to generate configure script:
You can also run the above commands in Cygwin environment on MS Windows platform. For more information on Cygwin, please refer to:
If you run configure script, it will generate not only makefile, but also mgconfig.h file base on the options of the configuration script. Afterwards, you just need to run make and make install commands to compile MiniGUI, and MiniGUI library and header files will be installed into the system's default directory or one directory which is specified by an option.
There are lot of options defined by MiniGUI configure script, each corresponding to a macro in mgconfig.h. If you enable an option when running configure script, the corresponding macro will be defined; otherwise the macro is undefined.
You can run the following command to list all options supported by the configure script:
You will obtain the whole options detailed list. For instance, supposing you use Ubuntu Linux 18.04 LTS as your development environment, the command runs in the MiniGUI source code directory and the out is as following (may be different on other Linux distributions):
By using the options listed above, we can tailor the features of MiniGUI easily. For example:
The command above will configure MiniGUI to MiniGUI-Standalone runtime mode, and use the incore resource.
Another example, if you run:
Your MiniGUI version will lack support for cursor and screen saver function.
We implement all of the configuration options of MiniGUI based on --disable-FEATURE and --enable-FEATURE. While MiniGUI configure script also provides --with-configuration option, you can use this option to choose one from multiple options. For example, you can use --with-osname=ecos option to specify the operating system on which MiniGUI runs.
For detailed description of the options, please refer to Compile-time Configuration.
If you run configure script without any option, it will generate makefiles and mgconfig.h file with default configuration options.
Each compile-time configuration option provides a default setting in its explanation: <default=yes> (the compile-time configuration option is enabled by default) or <default=no> (the compile-time configuration option is disabled by default).
Besides the configuration options defined by MiniGUI, the configure script also provides some important general options for compile-time configuration.
Prefix Option
This compile-time configuration option specifies where the MiniGUI library is installed. The default installation path is /usr/local. If you run:
After executing make install, the function library, the header files and the reference documents will be installed in /home/test/lib, /home/test/include, and /home/test/man respectively.
Cross Compiling Options
The compile-time configuration options --build, --host and --target are very important for cross compilation.
For example, if you use the arm-linux-gcc cross compiling toolchain, you need to correctly specify --build option, which lets configure script generate makefile suitable for cross compilation for ARM:
Once you have configured MiniGUI using the command above, you can run make command to cross-build MiniGUI for your target system. Under this situation, the C source files will be compiled using arm-linux-gcc command instead of the default gcc command in your system.
In above command, the --prefix option is used to set the installation directory’s prefix. After cross-building MiniGUI, when you execute make install command, the runtime configuration file, the library file and header files will be installed in the following directories respectively.
/usr/local/arm/2.95/arm-linux/etc//usr/local/arm/2.95.3/arm-linux/lib//usr/local/arm/2.95.3/arm-linux/include/
--enable-static and --enable-shared
These two configuration options control whether generating static function libraries or dynamic function libraries. If you do not need to generate static libraries, then you may use the --disable-static configuration option, it will take less time to compile the libraries than default.
Configuring MiniGUI in Non-GNU Environment
For some traditional embedded operating systems supported by MiniGUI, the user can usually use Integrated Development Environments running on MS Windows, such as Tornado, ADS, etc. Because these environments do not provide the toolchain that is GNU compatible, we are unable to use the configuration script to generate makefile and mgconfig.h file automatically.
Under this situation, you need to revise the mgconfig.h file manually for the compile-time configuration. Fortunately, FMSoft has already prepared a basic mgconfig.h file for these operating systems in build/ directory of MiniGUI source tree. For example, the file config-vxworks-i386.h in this directory can be used for VxWorks operating system running on i386.
As an alternative way, you can use the autoconf configuration script on Linux or Cygwin on MS Windows to generate a mgconfig.h file automatically for your target operating system. For example:
The command above will generate a mgconfig.h for VxWorks operating system. Note that this file is not the final version, but it can be used as a good starting point for your target system. The following code shows some key macros defined for the target system:
However, you need to check the macros with HAVE_ prefix in the file to meet the abilities of your target system. For example, you may comment out the following macros for most RTOSes:
Once you get a suitable mgconfig.h file for your target system, you can use makefile.ng makefiles shipped with MiniGUI source tree to build the MiniGUI library.
For more information, please refer to Building MiniGUI in Non-GNU environment.
Building MiniGUI in GNU Environment
Before building MiniGUI, you need to install the dependent libraries required by MiniGUI first. MiniGUI uses librreetype, libpng, libjpeg, libz and some other third-party libraries.
These dependent library source code packages basically use GNU automake/autoconf scripts to organize projects and compile/install these libraries by specifying specific environment variables and certain options when running ./configure commands. You can also check the acceptable options for each configuration script by running ./configure --help in the source tree directory.
Currently, these dependencies have standard software packages on Linux distributions (such as Ubuntu, or RedHat). Therefore, if you want to develop MiniGUI apps on a Linux system, you can directly install these software packages. For example, on Ubuntu Linux 16.04, the development packages for librreetype, libpng, libjpeg can be installed by executing the following command:
This section describes the basic commands to compile the dependent libraries from source code.
LibFreeType
The FreeType Library is an open sourced, high quality, and portable font engine which provides a unified interface for accessing a variety of font format files including TrueType, OpenType, Type1, CID, CFF, MS Windows FON/FNT, X11 PCF, etc. MiniGUI mainly uses the FreeType library to render TrueType, OpenType, and Type 1 fonts.
Historically, FreeType has two major versions, one is FreeType 1, such as FreeType v1.3.1; the other is FreeType 2, such as FreeType v2.6.2. Currently, FreeType 1 is deprecated, so MiniGUI provides support for FreeType 2 only.
Download the source code package of FreeType 2 from the official website of MiniGUI or the FreeType official website and unzip it into the source directory, then run the following commands:
The FreeType 2 library and header files will be installed into /usr/local directory.
LibJPEG, LibPNG, and LibZ
To support various image formats, MiniGUI uses LibJPEG for JPEG images, LibPNG for PNG images. The support for Windows BMP and GIF is self-contained, it does not need a third-party library.
Like the FreeType library, these libraries are also included in common Linux distributions.
To support PNG images, we first install the LibZ library. The LibZ library provides compression and decompression functions using the Z algorithm, while the PNG image format uses the same algorithm.
Download and unzip LibZ library source code package, enter into the top directory of the source tree, and execute the following commands:
The LibZ library and the header files will be installed into /usr/local directory.
Download and extract the LibPNG library source code, enter into the top directory of the source tree, and execute the following commands:
Download and extract the LibJPEG library source code, enter into the top directory of the source tree, execute the following commands:
The header files, the dynamic libraries and the static libraries will be installed into the /usr/local directory.
gvfb
gvfb is a virtual frame buffer graphics engine. Developers use gvfb on a PC as the display device of MiniGUI. In this way, we can easily develop MiniGUI app on a Linux system.
The default virtual frame buffer graphics engine in MiniGUI 3.0 or later is pc_xvfb. The graphics engine defines a virtual frame buffer (XVFB) specification that does not depend on a specific implementation. Under this specification, we can use the gvfb program on Linux (based on Gtk+ 2), or use the qvfb2 program (based on Qt) to display the output of MiniGUI and its apps in the window of gvfb or qvfb2.
To compile and install gvfb, make sure that you have installed Gtk+ 2.0 development packages. With Ubuntu Linux, use the following command to install the appropriate development packages:
Then enter the top directory of gvfb source tree, run the following commands:
MiniGUI Core
Once MiniGUI is configured successfully, you execute make command at the top directory of MiniGUI source tree to build MiniGUI:
This command will do the default building work. But you can also specify a different target to run make command to do other building work, for example,
This will remove previously generated object files or libraries.
There are several predefined targets in the makefile generated by configure script. The frequently-used targets are listed as follow:
make allormake: The default building process: compile the source code, then link object files to generate the library or the executable files.make clean: Clean object files.make install: Install the executables, libraries, header files, and so on to the installation directory.make uninstall: Uninstall the executables, libraries, header files, and so on from the system.
Therefore, you genenrally use the following commands to configure, build, and install MiniGUI:
You can also use configure script to specify a cross-compiling options and the prefix of installation directories.
MiniGUI resource
MiniGUI resource package (minigui-res) is also organized by GNU autoconf/automake script, so just run the following command to install:
Similarly, you can also specify the installation path using the --prefix option.
MiniGUI components
After building MiniGUI Core, it is very straightforward to building MiniGUI components, because they use the same way to organize the source code, and there are a few configuration options.
Here is a Bash shell script to build the MiniGUI components:
MiniGUI samples and demos
After compiling and installing MiniGUI Core and components according to the above steps, you can compile and run the sample in mg-samples.
By default, MiniGUI will use the pc_xvfb graphics and input engine, and the actual virtual frame buffer program is gvfb.
Run the following commands to configure and compile the mg-samples code package:
The first command will refresh the Linux system dynamic library cache system. By default MiniGUI dynamic libraries are installed in the /usr/local/lib directory, the system uses a cache to maintain a list of all the dynamic libraries installed in the system. If the cache is not refreshed, the system may complain no dynamic library found.
To run the demo in MiniGUI-Processes runtime mode, you need to start the mginit program first and then run other sample programs. The following commands give the process of running a game (same) in MiniGUI-Processes mode:
On MiniGUI-Threads runtime mode, you can directly run a sample. Here's how to run the game same:
In the same way, you can build and run mguxdemo (cell-phone-ux-demo) and mg-demos easily.
Building MiniGUI in Non-GNU Environment
In a Non-GNU development environment (generally, a toolchain runs on MS Windows), you can organize the source code files of MiniGUI Core and components as one project (or multiple projects) in the Integration Development Environment (for example, Tornado or ADS) to compile them. Before compiling, you should make sure that there is a correct mgconfig.h header file for your target system. For more information, please refer to Configuration Header File.
But we recommend that you use Cygwin to build and install MiniGUI Core and components on MS Windows. In theory, this method is suitable to any development environment which runs on MS Windows. Therefore, we give a detailed description on this method in this section.
Cygwin is a large collection of GNU and open source tools which provide functionality similar to a Linux distribution on MS Windows. You can download Cygwin from https://www.cygwin.com/.
After installing Cygwin on MS Windows, you can execute many GNU and open source tools. For example, BASH scripts, VIM editor, PERL script interpreter, make tool, gcc compiler, and so on. Please make sure you have selected to install these packages when you install Cygwin.
Note that in Cygwin environment, you can also execute MS Windows commands like the building toolchain of your target system. Thus, if you write makefiles for MiniGUI according to the GNU rules and use make tool of Cygwin to execute the corresponding compiler and linker, you can compile, link, and generate MiniGUI libraries easily for the target system.
In order to compile MiniGUI conveniently in Cygwin, we provide a separate set of makefiles with a postfix .ng in MiniGUI Core. Here the postfix ng means non-GNU.
In the top directory, there is a file named rules.make. This file defines the global rules for makefile.ng, and you need to define a correct TARGET_RULES variable for your target system.
By default, TARGET_RULES variable is defined as:
And the content of build/rules-pc.linux is as follow:
Note that this makefile.ng can work on Linux; we can compile MiniGUI Core using the following commands on Linux:
The first command generates mgconfig.h for Linux, and the second command compiles MiniGUI Core.
Also note that makefile.ng will only build static library.
For easy usage, we have provided some ready-to-use rules files for different target systems in build/ directory. There are also configuration header files for such systems.
For example, assume that you use VxWorks toolchain on MS Windows:
build/rules-pc.vxworks: the rules for VxWorks on i386 target.build/config-vxworks-i386.h: the configuration header file for VxWorks on i386 target.
First, you copy the header files into the top directory and overwrite the default mgconfig.h:
Second, you modify the rules.make file in the top directory to use the real rules:
Third, you compile MiniGUI using make tool of Cygwin:
Note that makefile.ng supports clean and install targets. If you execute the command as follow:
You can install MiniGUI header files and library to the directory, which is specified by rules-<platform>.<os>. If you execute the command as follow:
You can clean all object files generated by last make command.
Note that if you modify mgconfig.h and other files in the Cygwin environment, you should execute make -f makefile.ng clean to clean all object files, then re-compile MiniGUI.
To correctly use makefile.ng in Cygwin environment to compile MiniGUI, you should make sure to prepare a correct rules.make file. You must define the variables accurately in the following table.
The variables needed by makefile.ng
CC
Specify C compiler
CPP
Specify C++ compiler
AR
Specify archiving tool, the tool is used to generate static library
RANLIB
Specify static library index tool
MAKE
Specify make tool
Generally, the make tool is /usr/bin/make in the Cygwin environment.
ARFLAGS
The option that controls the archiving tool generate static library
COFLAG
The option that it control the compiler to compile, but not link
OBJ
The suffix name of the object file
LIBA
The suffix of the static library file
PREFIX
The prefix of the installation directory
INCS
Specify the search directories of header file
CFLAGS
The C compiler option
The content of build/rules-pc.vxworks is listed as follow:
Note that the make tool will install MiniGUI header files to the $PREFIX/include/minigui directory, and the MiniGUI Core library will be installed into the $PREFIX/lib/ directory. Therefore, the rules.make file above will install MiniGUI header files into c:/cross/include/minigui directory and MiniGUI Core library into c:/cross/lib directory.
By referring to the table and the rules.make file above, you can write a correct rules.make file based on your actually development environment and toolchain.
Because the format of the makefile.ng is compatible with GNU makefile, so we can use makefile.ng to compile MiniGUI in the Linux environment, actually. This kind of circumstance usually occurs while using cross-compiling toolchain for uClinux. If you work in Linux environment, you can execute make command directly:
For MiniGUI components, you can use the same way to compile them in non-GNU environment; we do not repeat them here.
<< Quick Start | Table of Contents | Compile-time Configuration >>
Last updated