1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
|
# FAQ
## Managing Binary Size
This package adds about `900K` to any binary that depends on it.
Prior to 2019-05-16, this package could add about `2MB` to the size of
your binaries. We have now trimmed that by 60%, and the package
contributes less than `1MB`. This compares favorably to other packages like
`json-iterator/go` `(1MB)`.
Of that `900Kb`, about `200Kb` is from an *optional* auto-generated file:
`fast-path.generated.go` that includes static generated implementations
providing much faster encoding and decoding of slices and maps
containing built-in numeric, boolean, string and interface{} types.
Furthermore, you can bypass including `fast-path.generated.go` in your binary,
by building (or running tests and benchmarks) with the tag: `codec.notfastpath`.
go install -tags codec.notfastpath
go build -tags codec.notfastpath
go test -tags codec.notfastpath
With the tag `codec.notfastpath`, we trim that size to about `700Kb`.
Please be aware of the following:
- At least in our representative microbenchmarks for json (for example),
passing `codec.notfastpath` tag causes a clear performance loss (about 10%).
*YMMV*.
- These values were got from building the test binary that gives > 90% code coverage,
and running `go tool nm` on it to see how much space these library symbols took.
We consider that your use will touch much less of the library and you can be sure
that it will add less than 1MB to your binary.
## Resolving Module Issues
Prior to v1.1.5, `go-codec` unknowingly introduced some headaches for its
users while introducing module support. We tried to make
`github.com/ugorji/go/codec` a module. At that time, multi-repository
module support was weak, so we reverted and made `github.com/ugorji/go/`
the module.
However, folks previously used go-codec in module mode
before it formally supported modules. Eventually, different established packages
had go.mod files contain various real and pseudo versions of go-codec
which causes `go` to barf with `ambiguous import` error.
To resolve this, from v1.1.5 and up, we use a requirements cycle between
modules `github.com/ugorji/go/codec` and `github.com/ugorji/go/`,
tagging them with parallel consistent tags (`codec/vX.Y.Z and vX.Y.Z`)
to the same commit.
Fixing `ambiguous import` failure is now as simple as running
```
go get -u github.com/ugorji/go/codec@latest
```
### Removing requirements cycle in v1.2.8
Unfortunately, due to the requirements cycle noted above, we cannot create a
valid `go.sum` until after the git version tags have been created. This is why
a `go.sum` has not been distributed with these 2 modules above.
To fix that, starting with codec `v1.2.8`, we will remove the requirements cycle.
`github.com/ugorji/go/` will require `github.com/ugorji/go/codec`
but not vice versa. It has been over 3 years since we released `v1.1.7` (in July 2019)
with the requirements cycle to accomodate folks with an older version of
the `github.com/ugorji/go` module. We believe most folks now depend
either directly on the newer `github.com/ugorji/go/codec` module, or
on a newer `github.com/ugorji/go` module.
## Running on GCCGO
You can use [gccgo](https://gcc.gnu.org/onlinedocs/gccgo/) [1](https://golang.org/doc/install/gccgo)
to build your applications that depend on this library.
This is fully tested.
There's a caveat for contributors to the library.
If you are contributing to the library, you will need to run `./build.sh -m` at some point.
This has a failure on gccgo. Consequently, contributors must use the `gc` compiler.
|
