src/coreclr/tools/mcj-edit/README.md

   1 # MCJ profile editor
   2
   3 `mcj-edit.py` is MCJ profile editor, see `--help` for all available options, see `help` for mcj profile short summary and for binary signature short summary.
   4
   5 See `examples/` for examples of mcj profiles.
   6
   7 ## Examples of usage
   8
   9 ### To show mcj profile format summary:
  10
  11 ```sh
  12 python3 mcj-edit.py help --mcj-format
  13 ```
  14
  15 ### To show binary signature format summary:
  16
  17 ```sh
  18 python3 mcj-edit.py help --binary-signature-format
  19 ```
  20
  21 ### To show help:
  22
  23 ```sh
  24 python3 mcj-edit.py --help
  25 ```
  26
  27 ### To verify profile correctness:
  28
  29 ```sh
  30 python3 mcj-edit.py verify -i `pwd`/profile.dat
  31 ```
  32
  33 ### To print profile:
  34
  35 ```sh
  36 python3 mcj-edit.py print -i `pwd`/profile.dat
  37 ```
  38
  39 Add `--raw` option to print raw profile, i.e. the way it is saved in file.
  40
  41 Add `--header`, `--modules`, `--module-deps-and-methods` options to print only parts of profile.
  42
  43 ### To find method or module in profile:
  44
  45 ```sh
  46 python3 mcj-edit.py find -i `pwd`/profile.dat --module System.Private.CoreLib --method-token 100663502
  47 ```
  48
  49 Use `--module` option to find module by name, `--method-token` to find generic/non-generic method by token.
  50
  51 ### To compare profiles:
  52
  53 Using load and compare:
  54 ```sh
  55 python3 mcj-edit.py compare -i `pwd`/profile.dat -i /tmp/profile2.dat
  56 ```
  57
  58 To use sha256sum on files add `--sha256` option.
  59
  60 ### To split profile in app-dependent and app-independent:
  61
  62 ```sh
  63 python3 mcj-edit.py split -i `pwd`/profile.dat --system-modules-list `pwd`/system_modules.txt
  64 ```
  65
  66 After this command two new files will be created: `pwd`/profile.dat.app for app-dependent profile and `pwd`/profile.dat.sys for app-independent profile.
  67
  68 ### To merge profiles:
  69
  70 ```sh
  71 python3 mcj-edit.py merge -i `pwd`/profile.dat -i /tmp/profile2.dat -o `pwd`/profile.merged.dat
  72 ```
  73
  74 After this command new file wil be created: `pwd`/profile.merged.dat.
  75
  76 **Note: merge can't be performed on two arbitrary mcj profiles! Next profiles can't be merged:**
  77 - if one profile contains module with name `AAA` and version `X` and another profile contains module with same name `AAA` and version `Y`
  78 - if one profile contains module with name `AAA` and assembly name `BBB` and another profile contains module with same name `AAA` and assembly name `CCC`
  79 - if one profile contains module with name `AAA` with flags `X` and another profile contains module with same name `AAA` with flags `Y` (this situation should not happen now, flags are always 0)
  80 - if one profile contains method with token/signature `XXX` with flags `X` and another profile contains method with same token/signature `XXX` with flags `Y` (this situation can happen now only if one profile was rewritten during use, i.e. JIT_BY_APP_THREAD_TAG was not set for some methods, i.e. COMPlus_MultiCoreJitNoProfileGather=1 was not set)
  81
  82 ### To run some tests:
  83
  84 ```sh
  85 python3 mcj-edit.py self-test --rw-sha256 -i `pwd`/profile.dat
  86 python3 mcj-edit.py self-test --rw -i `pwd`/profile.dat
  87 python3 mcj-edit.py self-test --sm -i `pwd`/profile.dat --system-modules-list `pwd`/system_modules.txt
  88 ```
  89
  90 ## pylint
  91
  92 To run pylint:
  93 ```sh
  94 pylint -d superfluous-parens,missing-function-docstring,missing-class-docstring,missing-module-docstring,too-many-boolean-expressions,too-many-arguments,too-many-public-methods,too-many-lines --max-line-length=120 --method-naming-style=camelCase --argument-naming-style=camelCase --attr-naming-style=camelCase --variable-naming-style=camelCase mcj-edit.py
  95 ```