FreshLib is an assembly library aimed to ease the development of assembly language applications, freely portable between different platforms, such as Win32 or Linux.
The library is coded in flat assembler syntax and is intended to be easily used within Fresh IDE, although it could be used for plain FASM development.
The library consists of two layers: one, that is OS dependent and a second one that is OS independent. The OS dependent layer is very small, in order to help porting it for different OSes. This layer only makes interface to the core OS functions, such as memory allocations, file access, drawing functions, simple window management etc.
The OS independent layer is responsible for the main application functionality allowing creation of different kind of windows and controls, although it could be used for plain FASM development.
FreshLib is mainly intended for developing GUI applications, as they are the most challenging to be ported across different platforms. FreshLib is also created with visual programming in mind, so it contains a flexible, event driven and OS independent template engine allowing visual creation of application user interfaces.
FreshLib is in early development stage and probably will be changed many times in order to reach their objectives: to be small, fast and easy to use.
The main intention is to keep the bloat off the library, but containing all necessary accessories for comfortable programming of a very wide range of applications.
The architecture of FreshLib is open and it can be freely expanded with other libraries without increasing the size of applications. In other words, only those parts of the library that are effectively used will be compiled on the final executable.
2. About this manual
This manual is a "work in progress". Any part of it can be changed at any time.
Of course, some of the libraries described in this document are more stable and finished like the macro, system and data libraries. Therefore, the chapters about these libraries are less likely to be changed. Other libraries (like graphics and GUI), will be heavily modified so the manual will be changed accordingly.
3. Structure of the library.
FreshLib contains many code and macros libraries, structured hierarchically and depending on each other. Here is shown a part of the library directory tree:
freshlib/ compiler/ Linux/ Win32/ data/ Linux/ Win32/ dialogs/ Linux/ Win32/ ...
The library is structured to support different platforms transparently. You can see, that the tree consists of main sub-directories, that contains OS independent libraries, separated by topics. For example system subdirectory contains libraries for accessing system resources such as memory, files, etc. data contains libraries for data handling and so on. Every topic directory have also several sub-directories, that contains OS dependent code these directories are named after the platform they serve. (In this moment only Linux and Win32 OSes are supported).
4. Compiler setup for FreshLib use.
You can use any FASM compiler to compile applications that uses FreshLib. In order to be compiled properly, FreshLib needs environment variables named lib and TargetOS to be defined.
The variable lib contains the path to the main directory of FreshLib and the variable TargetOS contains the target platform, the application will be compiled for. The value of TargerOS is identical to the name of OS dependent directories in FreshLib.
Currently, there are 3 of them: Win32, Linux and KolibriOS. Setting TargetOS to some of these values will make the program to be compiled for this OS.
There are several ways these variables to be defined, depending on the compiler you use FASM, FASMW or Fresh IDE:
These variable can be defined in the OS environment - see your OS documentation for details. this approach is more universal - it works for all kind of FASM compilers. The main drawback is that you have to use OS specific commands and probably will have to edit some system files.
Definition in the section
"Fresh.ini"file, depending on the IDE you are using. This approach works for both FASMW and Fresh IDE, but in Fresh, the same effect can be done from inside the IDE. Besides, defined this way, the environment variables becomes "global" - active for all projects compiled with FASMW or Fresh.
From inside Fresh IDE.
In Fresh IDE, the environment variables are named
"alias", because they serve to provide short alias for the file paths. Two types of alias (environment variables) lists are supported by Fresh:
global aliases and
project aliases. Global aliases are defined in the IDE options dialog:
Options|IDE options|Aliases. Here is the screenshot of this dialog:
The global aliases are active for every project compiled with Fresh and are stored in the
Fresh.ini file, inside the Fresh program directory.
Project aliases are defined in the Project options dialog:
Project|Project options or from the project manager, click on the button Settings at the top and select Project options. The project options dialog is shown on the following screenshot:
The project aliases are stored inside the project file
(.fpr) and they are project specific.
For FreshLib it is not important what list will be used, but it is more convenient for lib variable to be defined in the global list and for TargetOS variable to be defined in the project aliases. In such way the common parameter (the place of the library) will be set once for all projects, and the particular parameter (the target OS) will be set separately for every project.
Also, there is very convenient way of changing the value of project aliases — if several values are specified in the project alias, separated with | char (for example: Win32|Linux), Fresh will provide fast switching between these values from the project manager options menu, as shown on the picture:
When Fresh searches for needed alias names, during the compilation, it searches first in the project aliase list, then the global aliases and at the end, the OS environment variables. Of course, if the alias is not found on these places, the compilation fails with error.
5. FreshLib compiling options
FreshLib uses some options in order to set the behavior of the compiler and the different macro libraries. These options are defined as a local constants of the label "options." Here is a list:
options.FastEnter controls the behavior of the proc macro.
When options.FastEnter = 1 the procedure entry/leave code will be created with faster, but bigger push ebp/pop ebp instructions.
When options.FastEnter = 0 — enter/leave instructions are used.
options.ShowSkipped controls the information displayed during compilation.
When options.ShowSkipped = 1 the compiler will display in the output window the procedures that are not compiled because they are not used in the program.
options.ShowSizes controls the behaviour of the DispSize macro.
When options.ShowSizes = 0 the macro DispSize will be disabled.
options.DebugMode controls the behaviour of the debug macros.
When options.DebugMode = 1 the macros from simpledebug library will generate debug code and debug console will be created on running the application.
When options.DebugMode = 0 these macros will not generate code and the debug console will not be created.