There is still no full user guide for Fresh.

I will write in this page some tips and tricks. Later, they will be used in the full user guide.

Fresh IDE contains an index of the help files in a file %FreshHelp%/index.help. Every row in this file, contains a relative path to a single help file that to be searched when F1 is pressed in the Fresh IDE editor.

Fresh IDE supports following help file formats:

They work good only in Windows. In Linux, Wine has CHM viewer, but essential features are not supported.

The support in Linux is a little bit better, but still not very useful.

Fresh IDE searches the html files, scanning for anchor tag with ID containing the keyword searched. For example, searching %FreshHelp%/FASM.html file for movsw keyword, Fresh will find the anchor <a id="movsw21148">.

Then Fresh IDE will start the configured web browser on URL http://127.0.0.1:7000/FASM.html#movsw21148

Notice, that Fresh IDE uses built in web server to handle such files.

These files are simple text file, containing index of URLs. The format of the file is:

Empty lines and lines starting with ";" are ignored. The file must contains a special keyword __index_main_file that to point to the main file URL.

In Fresh IDE, the Linux system calls help is organized this way. See %FreshHelp%/lscr/index.idx for example.

Similar to the .html files, Fresh IDE searches for anchor tags.

In markdown format they looks like: [#KEYWORD] at the beginning of the line.

Once the keyword has been found, Fresh opens the web browser at URL: http://127.0.0.1:7000/helpfile.md#KEYWORD

Fresh IDE v2.1.9 and newer contains a built-in web server in order to handle the help files of different types.

This web server binds only to 127.0.0.1 IP address and automatically searches for accessible port in the range of 7000..9999.

The web server automatically renders the markdown formatted help files to .html and send them to the browser.

In order to use the online help system, Fresh IDE needs to know the path to some web browser.

Usually, on the first run (or if Fresh.ini file has been deleted) Fresh will try to guess the default OS web browser.

In Windows it will check the registry. In Linux /usr/bin/xdg-open command will be used.

Later, the user can change this setting from Options|IDE options|Other options|Web browser.

There are three more options for the help system:

"Try google as a last hope" - if checked and the searched keyword has not been found in the configured help files, Fresh IDE will try to search with google.com for the specified keyword.

If "I'm feeling lucky" option is checked as well, the browser will go directly to the first found web site.

"Ignore WinApi suffix on search" - if checked the system tries to detect the "A" or "W" suffix on the searched keyword and removes it, in order to provide better search results, because the API functions are usually specified without this suffix.

The former two options works very good for searching Windows API functions - in most cases it navigates directly at the proper page in MSDN.

How to develop Linux application from Windows?

How to develop Windows application from Linux?

What about Fresh IDE version for Linux?

For now, Fresh is Windows application. The versions 2.x.x will be Windows applications. The upcoming v3.0.0 is planed to be portable - for Windows and Linux. Of course every port will be able to create applications for every OS.

Despite of this situation, even the current versions can work in Linux through Wine.

There is a separate setup manual describing the setup of Fresh IDE for Linux development.

How to find the place in the source where application crashes?

Press Ctrl+G in order to open "Goto address" dialog:

Then enter the address where application crashes and press OK. Fresh will show you the line of the source that is compiled on the given address. The format of the number is standard FASM number format.

There are several functions, aimed to provide easy exploration the source of the big project.

This function displays in the scratch pad window the preprocessed code, generated from some line in the source. If the line contains macro invocation, the macro will be unrolled and the result code displayed in the hierarchical form in the window.

The function can be activated by pressing Ctrl+U shortcut when the caret is on the needed line or by using the editor context menu - "Unroll macro".

The source must be compiled and this file to not be changed after compilation in order to use this function.

After compilation, you can browse all labels tree from the labels explorer. Open it from the main menu: Project|Label explorer. In the label explorer you can view the labels values, type and where in the source these labels were defined and used.

If you position the text caret on some label and press Ctrl+R, or choose from context menu "Cross reference", a window with the cross reference information for this label will be open.

The first row of the table display the line of the source, label was defined. Following rows - the lines where the label is used. Besides the pointed label, all its children labels will be displayed.s

If you double click on some of the rows, the editor will bring you to this line of source.

The cross reference window can be closed by pressing Esc key.

If you position the text caret on some symbol and press Ctrl+D or choose from the context menu "Goto definition", the editor will bring you to the line of the source where this symbol were defined. The project must be compiled for this function to work.

Similar to "Goto definition" is the next function "Embedded help".

If the definition of some symbol is preceded by comments block, describing this symbol, Fresh can show this description everywhere in the source, when you position the text caret on the symbol and press Ctrl+W shortcut.

The hint window looks like on the screenshot:

The hint window can be closed by pressing Esc key.

How to use "Procedure arguments hint"?

This function works with call macros: stdcall, ccall, invoke and cinvoke;

When you type such line and the function is known (the source have to be compiled prior to that moment) Fresh shows a hint window that helps you to enter the arguments. This happens automatically when you type "," somewhere in the line.

When you want to open the hint window without typing (just for check up) you can press Ctrl+Q when the caret is at the line. You can close the hint window, pressing Esc key.

"Procedure arguments hint" works for the procedures defined in the compiled source and if the program uses import definitions from FreshLib, for imported functions as well.

How to type less and to code more?

Code completion is very powerful function, that can save you thousands of keystrokes. In order to use it, the source have to be compiled (at least partially - some errors are acceptable) because Fresh have to build the tree of labels, defined in you program.

Fresh does not use fixed predefined lists. It uses the labels you defined in the source.

This is the only possible solution, because Fresh is not committed to any particular OS or platform. If you write Win32 program, you need Windows API and constants in the auto completion box. If you write Linux program, you need all Linux constants and API functions.

To open code completion, press Ctrl+Space shortcut. Then when you type, the content of the box will be refreshed in order to correspond with the word you type.

You can select suitable element from the list with Up, Down, PgUp and PgDn keys and press Enter to insert it in the line.

Auto completion list will open automatically when you type some existing in the list label and then press "." in order to select local label.

Auto completion works for the local labels as well:

You can close the auto completion window with ESC key.

How to move a file from one category to another in the project?

Open the file in the editor. Select the category where you want it to be moved. Click the right mouse button on the tab of the file in order to display the context menu. Select "Add to project" function. It will remove the file from the old category and will move it to the current selected category.

How to open the file specified in "include" or "file" directive?

Place the caret on the line that contains file name and press Ctrl+Enter. Opening files this way, Fresh replace the directory aliases and/or environment variables in the filename.

Files like %lib%/%TargetOS%/MyFile.asm will be opened correctly.

How to set promptly the values of the environment variables?

Fresh have very flexible system of environment variables handling. Actually I prefer to call them "Alias", because they are aliases of the directories or other text.

You can define such aliases in three ways:

As OS environment variable.

As IDE-wide aliases in the Fresh IDE options dialog ("Options|IDE options|Aliases" menu).

As Project-wide aliases in the project options (Project|Project options" menu or Ctrl+F12 shortcut)

When exists alias defined several times, then the project aliases have higher priority, then the IDE aliases and with lowest priority are the OS environment variables.

Now on the topic: The project aliases allows rapid value change. In order to use this feature, you have to define the alias with several values, delimited with "|" symbol. The count of different values is not limited.

One typical example is the alias %TargetOS% used in the FreshLib test project. This alias may have as values the names of the OS, the project will be compiled for. So, in order to switch quick from Win32 to Linux we can define TargetOS as "Win32|Linux".

In this case, at the top of the project window appears popup menu, where you can select what of these values to be used. Additionally, the panel "Settings:" will display currently selected values.

How to write portable assembly applications with Fresh IDE?

Most people think that assembly language can't be portable. It is not the case. There are many examples that assembly can be portable. It is only matter of the project design, not the language.

In order to allow creating of portable applications, FreshLib was created. It is work-in-progress, but even now it allows creating of small applications that can be compiled for Win32 and Linux platforms without change of the source.

Read the unfinished FreshLib reference manual and check the sources of FreshLib in "Fresh/freshlib" directory of your Fresh IDE installation. There is a working test project called TestFreshLib.fpr that I use to test different FreshLib features.

Also, you can create FreshLib projects from template engine. Choose "File|New Application" from the main menu or press Shift+Ctrl+N shortcut.

In the dialog window, select the target directory and application template - "FreshLib portable console application" or "FreshLib portable GUI application", then click "OK" and new project will be created.

Press Shift+Ctrl+S to save all new created files (you can change the filenames to whatever you like).

Then you can compile your application to Linux or Windows executable file.

The latest development version of FreshLib can be downloaded from the repository - FreshLibDev branch.