Compile Mono Resource Text Files with resgen

You will turn simple key=value text into Mono binary .resources files, then check that the generated files can be read back. The commands below use the installed Mono Resource Generator 6.8.0.105 from package mono-devel.

Allow about ten minutes. You need a shell, Mono's development tools and a writable temporary directory. This guide changes only files below a new directory in /tmp. It does not need elevated privileges. Do not use sudo for the examples.

1. Check the installed tool

Confirm which executable the shell will run and record its version:

$ command -v resgen
/usr/bin/resgen
$ resgen --version
Mono Resource Generator version 6.8.0.105

There is also a resgen2 executable on this installation. The manpage describes resgen2 as the variant with the -usesourcepath option, but the installed resgen help includes that option as /useSourcePath as well. Use the command version that is present on the machine where your build runs; do not assume another Mono release accepts exactly the same spelling.

2. Create a small text resource

Make a unique temporary workspace and write a resource file. A line beginning with # or ; is a comment. Resource values can contain escaped newline, carriage-return, tab and backslash characters.

work=$(mktemp -d /tmp/resgen.XXXXXX)
printf '%s\n' \
  '# labels used by the example' \
  'welcome=Hello, Ada!' \
  'shortcut=Save\\tCtrl+S' \
  'two_lines=first\\nsecond' > "$work/messages.txt"
sed -n '1,10p' "$work/messages.txt"

Keep the source as plain text while you edit it. Keys are the names your application will request later; changing a key is an application change, not just a formatting change.

Expected source:

# labels used by the example
welcome=Hello, Ada!
shortcut=Save\\tCtrl+S
two_lines=first\\nsecond

3. Convert one file explicitly

Pass the source followed by the destination. Giving the destination explicitly prevents a build script from silently writing beside an input file when that is not what you intended.

resgen "$work/messages.txt" "$work/messages.resources"
file "$work/messages.resources"

On this Mono version the conversion reports the resources it read and ends with Writing resource file... Done.. The file command identifies the result as data rather than ordinary text. The binary format is the one read by .NET's resource reader, so do not edit .resources in a text editor.

If you omit the destination, resgen uses source.resources. For example, resgen "$work/messages.txt" creates messages.resources in the same directory. That default is convenient for a one-off conversion, but an explicit destination is easier to audit in build logs.

4. Read the result back as a check

Conversion success is not the same as checking the contents you meant to publish. Convert the binary result back to text and inspect it:

resgen "$work/messages.resources" "$work/roundtrip.txt"
sed -n '1,10p' "$work/roundtrip.txt"

You should see the three keys, with the escaped values preserved. The order may differ from the source because the resource file is a key-value store, so compare keys and values rather than relying on line order:

tabbed=left\\tCtrl+S
welcome=Hello, Ada!
two_lines=first\\nsecond

5. Batch-compile several files

Use /compile before the resource specifications. Each item can be just a source path, which changes its extension to .resources, or a comma-separated source and destination pair.

printf '%s\n' 'menu.file=File' > "$work/english.txt"
printf '%s\n' 'menu.file=Fichier' > "$work/french.txt"
resgen /compile \
  "$work/english.txt,$work/english.resources" \
  "$work/french.txt"
file "$work/english.resources" "$work/french.resources"

The command creates both binary files. The explicit pair fixes the English output name; the French item uses the documented extension replacement and creates french.resources beside its source.

Common trap: putting /compile after a source path can make the command line fail because the switch must precede the resources. If a destination already exists, treat replacement as a build decision. Check the path first and do not point an example at a live resource file unless you have a backup or can regenerate it.

6. Use conditional text only on a known Mono version

The installed 6.8.0.105 help documents /define:SYMBOL1,SYMBOL2 for conditional inclusion in .txt files. This option is not shown in the older local manpage, so keep it tied to a tested Mono version:

printf '%s\n' \
  '#ifdef FEATURE' \
  'new_label=Enabled' \
  '#endif' \
  '#if ! OMIT' \
  'fallback=Included' \
  '#endif' > "$work/conditional.txt"
resgen /define:FEATURE "$work/conditional.txt" "$work/conditional.resources"
resgen "$work/conditional.resources" "$work/conditional-roundtrip.txt"
sed -n '1,10p' "$work/conditional-roundtrip.txt"

The round-trip output contains new_label=Enabled because FEATURE was defined, and contains fallback=Included because OMIT was not defined. If another machine rejects this option, remove the conditional directives or use the exact resource-generation version supported by that build.

7. Handle failures without guessing

• For an unknown extension or malformed input, read the diagnostic and inspect the source. The documented formats are text, .resources, .resx and .po; a file extension alone does not make its contents valid.
• If a file is unexpectedly overwritten, stop the build, restore it from version control or a backup, and fix the destination argument. There is no undo operation in resgen.
• If a .resx conversion refers to an unavailable assembly, the manpage says resgen loads referenced assemblies from Mono's assembly cache. Repair the dependency or run the conversion in the build environment that contains it.

The temporary workspace is safe to leave for inspection. Remove it only after you have finished checking the output, and verify the path before deleting anything. Never substitute a broad directory for "$work".