# man > enc2xs(1)

---
type: CommandReference
command: enc2xs
mode: man
section: 1
source: man-pages
---

## Quick Reference

- `enc2xs -M ModName file.ucm` — Build a Perl Encode extension from a single UCM file
- `enc2xs -M ModName dir/*.ucm` — Build extension from multiple UCM files in a directory
- `enc2xs -C` — Update `Encode::ConfigLocal` for on‑demand loading of the encoding
- `enc2xs -Q -O -o output.c -f input.fnm` — Compile encoding (used internally during `make`)
- `enc2xs -[options]` — General options (see below)

## Name

enc2xs — Perl Encode Module Generator

## Synopsis

shell
enc2xs -[options]
enc2xs -M ModName mapfiles...
enc2xs -C
## Description

`enc2xs` builds a Perl extension for use by `Encode` from either Unicode Character Mapping files (`.ucm`) or Tcl Encoding Files (`.enc`). It is used internally during the build of the `Encode` module, and can also be used to add custom encodings to Perl. No XS knowledge is required.

### Quick Guide (Typical Workflow)

1. Prepare a `.ucm` file (e.g., `my.ucm`).
2. Run:
   ```shell
   enc2xs -M My my.ucm
   
   This creates `Makefile.PL`, `My.pm`, `README`, `Changes`, and a `t/` directory.
3. (Optional) Place `.ucm` files in an `Encode/` subdirectory and run:
   ```shell
   mkdir Encode
   mv *.ucm Encode
   enc2xs -M My Encode/*ucm
   
4. Edit generated files (recommended: update POD and add tests).
5. Build the module:
   ```shell
   perl Makefile.PL
   make
   
6. Test:
   ```shell
   make test
   
7. Install:
   ```shell
   make install
   
8. To add the encoding to `Encode`’s demand‑loading list so that `use Encode;` loads it automatically, run:
   ```shell
   enc2xs -C
   
   This updates `Encode::ConfigLocal`.

### Unicode Character Map (UCM) Format

A UCM file contains:

- A header section (lines before `CHARMAP`) with keyword/value pairs:
  - `<code_set_name>` — Required.
  - `<code_set_alias>` — Optional.
  - `<mb_cur_min>` — Usually 1.
  - `<mb_cur_max>` — Maximum bytes per character.
  - `<subchar>` — Substitution character (e.g., `\x3F` for ASCII `?`).
- A `CHARMAP` section with lines of the form:
  
  <UXXXX> \xXX.. |N # comment
  
  Where:
  - `<UXXXX>` — Unicode code point in hex.
  - `\xXX..` — Encoded byte sequence.
  - `|N` — Fallback flag:
    - `|0` — Round‑trip safe.
    - `|1` — Fallback for Unicode → encoding (encode map only).
    - `|2` — Skip sub‑char mapping.
    - `|3` — Fallback for encoding → Unicode (decode map only).
- The section ends with `END CHARMAP`.

Comments start with `#`. Keep at least `U0000` to `U0020` as‑is unless on EBCDIC. Not all UCM features (e.g., `icu:state`) are implemented; algorithmical encodings (ISO‑2022 series) require a Perl module.

### Coping with Duplicate Mappings

To ensure round‑trip safety (`encode(decode($data)) eq $data` for `|0` entries):

- Sort the map in Unicode order.
- Mark duplicate entries with `|1` or `|3`.
- Ensure the `|1` or `|3` entry **follows** the `|0` entry.

Example from `big5-eten`:
ucm
<U2550> \xF9\xF9 |0
<U2550> \xA2\xA4 |3
This makes `\xF9\xF9` round‑trip safe. If the order were reversed, the `|0` mapping would be overwritten.

The `Encode` distribution includes `ucmlint` (check integrity) and `ucmsort` (sort mappings) under `Encode/bin`.

## Options

- `-M ModName` — Set the module name for the generated extension.
- `-C` — Update `Encode::ConfigLocal` for demand‑loading of the encoding.
- `-Q` — Quiet mode (used during compilation).
- `-O` — Optimize the compiled form (detect duplicates and substrings).
- `-o file` — Write compiled C output to `file` (default: `encode_t.c`).
- `-f file` — Read input file list from `file` (default: `encode_t.fnm`).

Other options implied by `-[]` may exist; see the full man page for details.

## Examples

### Example 1: Build a New Encoding from a UCM File

Complete workflow as shown in the Quick Guide above.

### Example 2: Handle Duplicate Mappings

In a UCM file, ensure round‑trip safety by placing the fallback entry after the primary:

ucm
<U2550> \xF9\xF9 |0
<U2550> \xA2\xA4 |3
## See Also

- [Encode](https://www.chedong.com/phpMan.php/perldoc/Encode/markdown)
- [perlmod](https://www.chedong.com/phpMan.php/man/perlmod/1/markdown)
- [perlpod](https://www.chedong.com/phpMan.php/man/perlpod/1/markdown)
- [ICU Home Page](http://www.icu-project.org/)
- [ICU Character Mapping Tables](http://site.icu-project.org/charts/charset)
- [ICU Conversion Data](http://www.icu-project.org/userguide/conversion-data.html)