github.com/lheiskan/zebrapack@v4.1.1-0.20181107023619-e955d028f9bf+incompatible/cmd/addzid/README.md (about)

     1  addzid
     2  ======
     3  
     4  Summary: addzid automatically adds `zid:"0"`, `zid:"1"`, ... tags to your Go structs.
     5  
     6  Given a set of golang (Go) source files, addzid will tag the public
     7  struct fields with sequential zid tags. This prepares your source
     8  so that it can be fed to the `zebrapack` codegen tool.
     9  
    10  
    11  to install: *run make*. This lets us record version info.
    12  --------
    13  
    14  use
    15  ---------
    16  
    17  ~~~
    18  use: addzid {-o outdir} myGoSourceFile.go myGoSourceFile2.go ...
    19       # addzid makes it easy to add ZebraPack serialization[1] to Go source files.
    20       # addzid reads .go files and adds `zid` tags to struct fields.
    21       #
    22       # options:
    23       #   -o="odir" specifies the directory to write to (created if need be).
    24       #   -unexported add tag to private fields of Go structs as well as public.
    25       #   -version   shows build version with git commit hash.
    26       #   -debug     print lots of debug info as we process.
    27       #   -OVERWRITE modify .go files in-place, adding zid tags (by default
    28       #       we write to the to -o dir).
    29       #
    30       # required: at least one .go source file for struct definitions.
    31       #  note: the .go source file to process must be listed last, after any options.
    32       #
    33       # [1] https://github.com/glycerine/zebrapack 
    34  ~~~
    35  
    36  
    37  zid tags on go structs
    38  --------------------------
    39  
    40  When you run `addzid`, it will generate a modified copy of your go source files in the output directory.
    41  
    42  These new versions include zid tags on all public fields of structs. You should inspect the copy of the source file in the output directory, and then replace your original source with the tagged version.  Of course you can always manually add zid tags to fields, if you prefer. However `addzid` simplifies this chore.
    43  
    44  If you are feeling especially bold, `addzid -OVERWRITE my.go` will replace my.go with the zid tagged version. For safety, only do this on backed-up and version controlled source files.
    45  
    46  By default only public fields (with a Capital first letter in their name) are tagged. The -unexported flag ignores the public/private distinction, and tags all fields.
    47  
    48  The zid tags allow the ZebraPack schema evolution to function properly as you add new fields to structs.
    49  
    50  windows build script
    51  ---------------------------
    52  see `build.cmd`. Thanks to Klaus Post (http://klauspost.com) for contributing this.
    53  
    54  -----
    55  
    56  TODO
    57  ----
    58  cleanup internals: `addzid` was adapted from `bambam`, an earlier tool for generating CapnProto schema from Go files. Much vestigial code could be deleted as it isn't needed for `addzid`'s purposes.
    59  
    60  Copyright (c) 2016, 2017 Jason E. Aten, Ph.D.
    61