tools/asterix/README.md

   1 # Asterix parser generator
   2
   3 *Asterix* is a set of standards, where each standard is defined
   4 as so called *asterix category*.
   5 In addition, each *asterix category* is potentially released
   6 in number of editions. There is no guarantee about backward
   7 compatibility between the editions.
   8
   9 The structured version of asterix specifications is maintained
  10 in a separate project:
  11 <https://zoranbosnjak.github.io/asterix-specs/specs.html>
  12
  13 The purpose of this directory is to convert from structured
  14 specifications (json format) to the `epan/dissectors/packet-asterix.c` file,
  15 which is the actual asterix parser for this project.
  16
  17 It is important **NOT** to edit `epan/dissectors/packet-asterix.c` file
  18 manually, since this file is automatically generated.
  19
  20 ## Manual update procedure
  21
  22 To sync with the upstream asterix specifications, run:
  23
  24 ```bash
  25 # show current upstream git revision (for reference)
  26 export ASTERIX_SPECS_REV=$(./tools/asterix/update-specs.py --reference)
  27 echo $ASTERIX_SPECS_REV
  28
  29 # update asterix decoder
  30 ./tools/asterix/update-specs.py > epan/dissectors/packet-asterix.c
  31 git add epan/dissectors/packet-asterix.c
  32
  33 # inspect change, rebuild project, test...
  34
  35 # commit change, with reference to upstream version
  36 git commit -m "asterix: Sync with asterix-specs #$ASTERIX_SPECS_REV"
  37 ```
  38
  39 ## Automatic update procedure
  40
  41 To integrate asterix updates to a periodic (GitLab CI) job, use `--update` option.
  42 For example:
  43
  44 ```
  45 ...
  46 # Asterix categories.
  47 - ./tools/asterix/update-specs.py --update || echo "asterix failed." >> commit-message.txt
  48 - COMMIT_FILES+=("epan/dissectors/packet-asterix.c")
  49 ...
  50 ```
  51