FCARM File Converter

Software utility to compile static web pages.

Software utility to compile static web pages.

The FCARM file converter reformats all web files into a single C-file which is then included and compiled into the project. All files are stored in the Virtual ROM File System.

Automatic Invocation

If configured accordingly, FCARM is called automatically during a project build. In a csolution project, this is possible with the help of a cmake-script or a cmake-project. The main difference lies in how the web content resources are provided. In an FCARM call with a cmake-script, the web resource files are listed in the csolution project file cproject.yml, whereas in an FCARM call with a cmake-project, only the web resource container directory is specified in the csolution project file. The cmake project then searches the resource directory and adds all files found there to the web resources.

CMake-script

To setup the CMake script, create a file fcarm.cmake in the local csolution project directory with the following content:

list(GET CMAKE_ARGV3 1 INPUT_DIRECTORY)
list(REMOVE_AT CMAKE_ARGV3 0 1)
foreach(ITEM ${CMAKE_ARGV3})
  cmake_path(GET ITEM FILENAME FILE)
  list(APPEND FILES ${FILE})
endforeach()
string(REPLACE ";" ",\n" FILES "${FILES}")
 
cmake_path(RELATIVE_PATH CMAKE_ARGV4 BASE_DIRECTORY ${INPUT_DIRECTORY} OUTPUT_VARIABLE OUTPUT)
cmake_path(GET INPUT_DIRECTORY FILENAME INPUT_DIRECTORY_NAME)
cmake_path(GET INPUT_DIRECTORY PARENT_PATH WORKING_DIRECTORY)
 
set(COMMAND_FILE "${CMAKE_CURRENT_BINARY_DIR}/Auto_FcArm_Cmd.inp")
file(WRITE ${COMMAND_FILE} "${FILES}\nTO ${OUTPUT} RTE NOPRINT ROOT(${INPUT_DIRECTORY_NAME})\n")
 
execute_process(COMMAND
  fcarm @${COMMAND_FILE}
  WORKING_DIRECTORY ${WORKING_DIRECTORY}
  RESULT_VARIABLE STATUS
)
 
if(STATUS AND NOT STATUS EQUAL 0)
  message(FATAL_ERROR "Failed to execute FCARM: ${STATUS}")
endif()

In the csolution project file cproject.yml add a list of all web resources under executes: node.

executes:
  - execute: Run_FCARM
    run: ${CMAKE_COMMAND} -P $input(0)$ $input$ $output$
    always:
    input:
      - $ProjectDir()$/fcarm.cmake  # CMake script directory
      - Web                         # Root directory for web resources
      - Web/index.htm
      - Web/pg_header.inc
      - Web/pg_footer.inc
      - Web/ad.cgi
      - Web/ad.cgx
      - Web/buttons.cgi
      - Web/buttons.cgx
      - Web/language.cgi
      - Web/lcd.cgi
      - Web/leds.cgi
      - Web/network.cgi
      - Web/system.cgi
      - Web/tcp.cgi
      - Web/xml_http.js
      - Web/arm.png
      - Web/home.png
      - Web/keil.gif
      - Web/llblue.jpg
      - Web/pabb.gif
    output:
      - Web.c                       # Output file for FCARM

• The first line under input: specifies the location of the cmake script file.
• The second line specifies the root directory for the web content.

CMake-project

To setup the CMake project, create a file CMakeLists.txt in the local csolution project's subdirectory FCARM with the following content:

# CMakeLists.txt for calling FCARM
# Find input files in the input base directory and in its subfolders using recursive scanning
# Format arguments and generate a steering command file, overcoming any command line length limitation
# Call FCARM using the steering command file, generating the source file in the expected output  
#
# Configuration Step: ${CMAKE_COMMAND} -G <generator> -S <source directory> -B <build directory> -DINPUT_DIRECTORY=<input base directory> -DOUTPUT=<output source file>
# Build Step: ${CMAKE_COMMAND} --build <build directory>
#
# <generator>: underlying generator build system, e.g. Ninja
# <source directory>: directory where this CMakeLists.txt resides
# <build directory>: directory for temp files
# <input base directory>: directory where input data is located
# <output source file>: path and filename of source file to be generated
 
cmake_minimum_required(VERSION 3.22)
include(ExternalProject)
 
project("FCARM" NONE)
 
file(GLOB_RECURSE INPUT ${INPUT_DIRECTORY}/*)
 
foreach(ITEM ${INPUT})
  cmake_path(RELATIVE_PATH ITEM BASE_DIRECTORY ${INPUT_DIRECTORY} OUTPUT_VARIABLE FILE)
  list(APPEND FILES ${FILE})
endforeach()
string(REPLACE ";" ",\n" FILES "${FILES}")
 
cmake_path(RELATIVE_PATH OUTPUT BASE_DIRECTORY ${INPUT_DIRECTORY} OUTPUT_VARIABLE RELATIVE_OUTPUT)
cmake_path(GET INPUT_DIRECTORY FILENAME INPUT_DIRECTORY_NAME)
cmake_path(GET INPUT_DIRECTORY PARENT_PATH WORKING_DIRECTORY)
 
set(COMMAND_FILE "${CMAKE_CURRENT_BINARY_DIR}/Auto_FcArm_Cmd.inp")
file(WRITE ${COMMAND_FILE} "${FILES}\nTO ${RELATIVE_OUTPUT} RTE NOPRINT ROOT(${INPUT_DIRECTORY_NAME})\n")
 
add_custom_target(FCARM ALL DEPENDS ${OUTPUT})
add_custom_command(OUTPUT ${OUTPUT} DEPENDS ${INPUT} ${INPUT_DIRECTORY}
  COMMAND fcarm @${COMMAND_FILE}
  WORKING_DIRECTORY ${WORKING_DIRECTORY}
)

In the csolution project file cproject.yml add command and parameters to invoke the FCARM file converter.

executes:
  - execute: Run_FCARM
    run: ${CMAKE_COMMAND} -G Ninja -S $input(0)$ -B ${CMAKE_BINARY_DIR}/FCARM/$Project$.$BuildType$+$TargetType$ -DINPUT_DIRECTORY=$input(1)$ -DOUTPUT=$output$ && ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR}/FCARM/$Project$.$BuildType$+$TargetType$ -- --quiet
    always:
    input:
      - FCARM   # CMake script directory
      - Web     # Input directory with "web files" for FCARM
    output:
      - Web.c   # Output file for FCARM

µVision project

For setup, go to Project -> Options for Target and select the Utilities tab. At the bottom, you can configure how FCARM compiles the image files. Here's an example:

Configure Image File Processing (FCARM) Dialog

Manual Invocation

FCARM can also be invoked from the command line. You will find the executable in your MDK installation's sub-directory \ARM\BIN. FCARM has the following syntax:

FCARM @commandfile

Where

• commandfile is the name of a command file that can contain an inputlist, outputfile, and directives. (See below.)

If you do not wish to use the command file, you can invoke FCARM like this:

FCARM <{>inputlist<}> <{> TO outputfile<}> <{>directives<}>

Where

• inputlist is a comma-separated list of files. The files get converted into one output file. File names must be specified with the file extension, but without the path information.
• outputfile is the name of the output C-file containing the converted web files.
• directives are commands and parameters that control the operation of the file converter. Available directives are:

Directive	Description
PRINT	Specifies the name of the listing file. Default is the base name of the output C-file with the extension *.LST.
NOPRINT	Disables the generation of the listing (LST) file.
PAGEWIDTH	Specifies the number of characters on a line in the listing file.
PAGELENGTH	Specifies the number of lines on a page in the listing file.
ROOT	Specifies the root path where web files are located relative to the project directory path.

Optimization

FCARM integrates a file optimization algorithm to compress files and creates more compact and smaller executable images. FCARM decides on the file extension which kind of compression is used. Each file group has a different compression and optimization flavor.

When the filename has the tilde prefix (for example, ~doStuff.js) then compression or certain compression optimizations are disabled. This is useful when debugging a file. It is hard to trace code compacted to a single line with no spaces, no comments, and no line feeds.

Compression and optimization is performed in two iterations. In a 2nd pass, further optimization is performed resulting in better code density.

Group	Extension	Optimization	~Optimization (disabled)
HTML	html htm inc	HTML compression Performs the following optimizations: replaces tab characters with spaces removes line-termination CR-LF characters replaces multiple spaces with a single space removes leading and trailing spaces removes space between two html tags (for example, <ul><li>)	no compression
CGI	cgi cgx	CGI compression Optimizes scripts for maximum performance on embedded web server: checks the script syntax replaces T,C,I,# script commands with tokens replaces tab characters with spaces removes line-termination CR-LF characters removes multiple spaces removes comments from script lines groups small t-commands	white space removal but without grouping of small t-commands
CSS	css	CSS compression Parses and removes redundant information: replaces multiple spaces with a single space removes line-termination CR-LF characters replaces tab characters with spaces removes /* and //-style comments removes redundant spaces inserted in the 1ststep removes spaces nearby a delimiter: :;{}	no optimization
JS	js	JS compression Parses and removes redundant information: replaces tab characters with spaces replaces multiple spaces with a single space removes line-termination CR-LF characters removes /* and //-style comments removes redundant spaces inserted in the 1ststep removes spaces nearby a delimiter: .,:;=!+-*\/&|<>(){}""?	no optimization
others	.*	not affected	not affected

Examples

The following command line converts and optimizes index.htm, creates the output C-file index.c, and creates the listing file index.lst.

FCARM index.htm

The following command line converts and optimizes a list of files, creates the output C-file web.c, and creates the listing file web.lst.

FCARM index.htm, keil.gif, llblue.jpg, system.cgi TO web.c

The following command line converts and optimizes a list of files, creates the output C-file Web.c, and suppresses the creation of the listing file (nopr - directive). The files are located in the project's sub-folder Web. This command reflects the settings from the configuration dialog as shown here.

FCARM index.htm, keil.gif, llblue.jpg, system.cgi TO Web.c nopr root(Web)

The following command line converts and optimizes a list of files, creates the output C-file web.c, and creates the listing file web.lst. The file doStuff.js is excluded from optimization.

FCARM index.htm, keil.gif, llblue.jpg, system.cgi, ~doStuff.js TO web.c

The following command line uses a command file.

FCARM @FCARM_command_file