Updating Legacy 825 Apps to run on 825 Gen2

1. Run the new 825 development environment VM (Virtual Machine). Open the Eclipse IDE (Integrated Development Environment).

2. Select "File" "Import" to import legacy project such as from USB flash. Alternatively, if the project is available in an SVN repository use "File" "New" "Project" "Checkout the projects from an SVN" to checkout the project.

3. Use the file manager in the VM to create a directory for the resulting compiled executable such as /srv/nfs/arm825/mnt/nand/apps/<projectname>

4. Right-click on the project in Eclipse and select "Build Configurations", "Manage..."

5. Click "New..." and type for the "Name:" input "Debug-ARM825". Select "Copy settings from "Existing configuration - Debug". Click "OK".

6. There is now a duplicated build configuration. We will change this configuration to compile for the new 825.

7. Right-click on the project and select "Properties...", Select "Settings". Make sure the "Configuration" is selected as "Debug-ARM825" and click the "Tool Settings" tab.

8. Some projects might have "Cross Settings" under "Tool Settings". If so change the "Prefix" from "m68k-uclinux-" to "aarch64-none-linux-gnu-" (Be sure to not leave out the final minus sign). If the "Cross Settings" is in the project the following steps 9-12 may then be skipped.

9. Select "GCC C++ Compiler". The "Command:" will show "m68k-uclinux-g++". Change this to "aarch64-none-linux-gnu-g++". This changes the compiler to compile for the ARM64 architecture.

10. Select "GCC C++ Linker". The "Command:" will show "m68k-uclinux-g++". Change this to "aarch64-none-linux-gnu-g++". This changes the linker to link the project for the ARM64 architecture. Linking is the process of combining the already compiled code modules and libraries to create the executable.

11. In some cases the project may also have a "GCC C Compiler". If so change the command to "aarch64-none-linux-gnu-gcc".

12. In some cases the project may also have a "GCC Assembler". If so change the command to "aarch64-none-linux-gnu-as".

13. Click "Apply".

14. Go back to "Tool Settings" and under "GCC C++ Compiler" select "Include paths". Click the green plus icon to add a path. Add the path "/opt/arm64include". If there is a "GCC C Compiler" section also add this path to the includes there.

15. Under the "GCC C++ Linker" select "Libraries". If libraries "pthread" and "rt" are not already listed add them. Add "${UI_LIBS}". The "${UI_LIBS}" is a code to use the environment variable "UI_LIBS" in the list. This environment variable is preconfigured in the development VM to specify multiple user interface libraries. Also add lines "${CAIRO_LIBS}", "${GLIB_LIBS}", "${CUPS_LIBS}", and "json-c". The "${CUPS_LIBS}" and "json-c" may not be needed for all recompile projects.

16. Under "Library search path". Edit existing library paths as appropriate. For example change "${workspace_loc:/lib825ev/Debug}" to "${workspace_loc:/lib825ev/Debug-ARM825}"

17. Click the green plus icon and add the library path "/opt/arm64lib"

18. Under "GCC C++ Compiler" select "Preprocessor". Click the green plus icon to add the symbol "ARM64=1" This is used for conditional compilation. If there is also a "GCC C Compiler" section select "Preprocessor under that and also add the symbol "ARM64=1".

19. Click the "Build Artifact" tab. Change the output prefix to "/srv/nfs/arm825/mnt/nand/apps/<projectname>/". This is where the completed app will be placed. Using this path will make it easy to test from an SSH connection into the 825. After the build configuration is built performing ". test825 <ipaddress of VM>" from an SSH connection to the 825 will automatically mount and change directory to /mnt/nfs/arm825/mnt/nand/apps path on the 825 which will be the parent directory of the project. From SSH then type "cd <projectname>" to enter the directory for the project. Type "./<projectname>_dbg" to launch the app.

20. Click "Apply and Close".

21. Also create a "Release" build. Repeat the steps above from step 4, except name the build configuration "Release-ARM825" and copy the configuration from the "Release" build configuration. For the "Library search path" standard libraries change them to "Release-ARM825". The debug build will output messages from DEBUG_MSG statements in the code on the console. These messages are useful for debugging. These messages will be left out when the release build is compiled. The release build executable will often be a smaller size file and may have improved speed. The release build must also be tested as it is possible for problems to only show up in a release build.

22. The "Post-build" step for the signature file should also be set or modified for the release build to run "appsign64" to create the signature file so that the app will show as a legitimate app in the application menu.

23. A few source code changes may be needed for proper operation on the 825 Gen2. If the app has USB import/export features it may use a fixed path "/mnt/fl1" for the USB drive. The USB drive path will not be the same on the 825 Gen2. Search the project for the string "/mnt/fl1" to find any code that should be changed. The library lib825ev has a function called FindFlashDrive for the 825 Gen2 to get the path string. The path may be similar to "/run/media/sda1" but it is best to use the FindFlashDrive function instead of a hard coded path.

24. Also (probably rare) if the app communicates with another system by serial port, network, or file import/export that interprets the data content as binary integers, floats, etc... it may be necessary to make changes to account for different ​endianness. The 825 Gen2 is ARM-64 little-endian, The Legacy 825 is Coldfire big-endian.

25. Before running the app for debugging from SSH it will often be necessary to create a directory on the 825 Gen2 for the app's data. Check the app header files to confirm the directory the app will use for configuration and data files. (The last part of the directory should normally match the project name and the release build executable name. Some newer apps may automatically check when starting up and create the directory if it does not exist)

    mkdir /mnt/nand/apps/<projectname>
    

If the data directory does not exist when running the app it is likely the display will show error messages about failing to write/read setup, configuration, or database files.

It is often desirable to add the command to the app startup code to check and create the directory if it does not exist.

main()
{
   // ... 
   MakeDirIfNotExists("/mnt/nand/apps/<projectname>");
   // ...
}

26. In the VM /srv/nfs/arm825/mnt/nand/apps/<projectname> directory it is helpful to create a script "mktgz.sh" to generate a release package to give to customers to install the app.

    #!/bin/sh
    # Create tgz archive for app distribution
    # Archive will contains app executable, signature file, and may have a bmp file
    # to show on the application menu button.
    # The menu icon must be saved as a 24-bit bmp. The width should be an even 4 pixels
    # such as 280 x 180
    # Additional files may be added. Documentation files (pdf format) will be available
    # in new style apps to view on the indicator in chromium from help/about screen.
    tar -czvf <projectname>.tgz <projectname> <projectname>.8sg <projectname>.bmp <projectname>.ver <documentfilename>.pdf
    

A legacy 825 app recompiled to run on the 825 Gen2 may appear similar to this:

Project Settings Reference

Compiler and Linker

Debug-ARM825 and Release-ARM825 build configurations

If properties sheet has a "Cross Settings" section set:

Prefix: aarch64-none-linux-gnu-

Tool Settings	Command
Cross G++ Compiler	g++
Cross GCC Compiler 1	gcc
Cross G++ Linker	g++
Cross GCC Assembler 1	as

₁ "Cross GCC Compiler" and "Cross GCC Assembler" items may not be present in all projects.

If properties sheet does not have "Cross Settings" section:

Tool Settings	Command
GCC C++ Compiler	aarch64-none-linux-gnu-g++
GCC C Compiler 1	aarch64-none-linux-gnu-gcc
GCC C++ Linker	aarch64-none-linux-gnu-g++
GCC Assembler 1	aarch64-none-linux-gnu-as

₁ "GCC C Compiler" and "GCC Assembler" items may not be present in all projects.

Preprocessor

Debug-ARM825 build configuration

Defined symbols	Description
DEBUG
ARM64=1

Release-ARM825 build configuration

Defined symbols	Description
ARM64=1

Includes

Debug-ARM825 and Release-ARM825 build configurations

Includes	Description
"${workspace_loc:/lib825ev/inc}" 1	Main 825 library
"${workspace_loc:/lib825lang/inc}" 2	825 Multi language
"${workspace_loc:/lib825sql/inc}" 3	825 SQLite
/opt/arm64include

₁ Older apps may use lib825 instead of lib825ev. In this case use "${workspace_loc:/lib825/inc}" Some older apps that use lib825 also use libapp. In this case the additional include path "${workspace_loc:/libapp/inc}" will be needed.

₂ 825lang is used by newer apps. This is not needed for recompile of older apps.

₃ Older recompiled apps may instead use sql or sql3_7_9. If it is sql it is recommended to change it to use sql3_7_9. To use sql3_7_9 library change include path "${workspace_loc:/libsql3_7_9/inc}".

Libraries

Debug-ARM825 and Release-ARM825 build configurations

Library	Description
825ev 1	Main 825 library
825lang 2	825 Multi language
825sql 3	825 SQLite
sqlite3 3	825 SQLite
${UI_LIBS}
${CAIRO_LIBS}
${GLIB_LIBS}
${PRT_LIBS} 4

₁ Older apps may use 825 instead of 825ev. Some older apps that use 825 also use app. In this case the additional library app will be needed.

₂ 825lang is used by newer 825 Gen2 apps. This is not needed for recompile of older apps.

₃ For newer apps it is preferred to use 825sql and sqlite3 for dynamically linked SQLite shared object that is already on 825 Gen2. Older recompiled apps may use sql3_7_9 instead of 825sql and remove sqlite3 line. sql3_7_9 is statically linked and includes the sqlite3 library.

₄ The development VM may need to be updated to have the PRT_LIBS environment variable. Refer to VM technical information

Debug-ARM825 build configuration

Library search path
${workspace_loc:/lib825ev/Debug-ARM825} 1
${workspace_loc:/lib825lang/Debug-ARM825} 2
${workspace_loc:/lib825sql/Debug-ARM825} 3
/opt/arm64lib

₁ Older apps may use lib825 instead of lib825ev. In this case use search path: ${workspace_loc:/lib825/Debug-ARM825} Some older apps that use lib825 also use libapp. In this case the additional library search path ${workspace_loc:/libapp/Debug-ARM825} will be needed.

₂ 825lang is used by newer 825 Gen2 apps. This is not needed for recompile of older apps.

₃ If sql3_7_9 library is used change search path to "${workspace_loc:/libsql3_7_9/Debug-ARM825}".

Release-ARM825 build configuration

Library search path
${workspace_loc:/lib825ev/Release-ARM825} 1
${workspace_loc:/lib825lang/Release-ARM825} 2
${workspace_loc:/lib825sql/Release-ARM825} 3
/opt/arm64lib

₁ Older apps may use lib825 instead of lib825ev. In this case use search path: ${workspace_loc:/lib825/Release-ARM825} Some older apps that use lib825 also use libapp. In this case the additional library search path ${workspace_loc:/libapp/Release-ARM825} will be needed.

₂ 825lang is used by newer 825 Gen2 apps. This is not needed for recompile of older apps.

₃ If sql3_7_9 library is used change search path to "${workspace_loc:/libsql3_7_9/Release-ARM825}".

Next Steps

Creating a simulator build configuration is also useful. Refer to Simulating 825 Gen2 Apps for information about setting up a simulator build configuration.

Also a next step may be: Updating Legacy Apps to New Look