github.com/akaros/go-akaros@v0.0.0-20181004170632-85005d477eab/src/cmd/dist/README (about)

     1  This program, dist, is the bootstrapping tool for the Go distribution.
     2  It takes care of building the C programs (like the Go compiler) and
     3  the initial bootstrap copy of the go tool.  It also serves as a catch-all
     4  to replace odd jobs previously done with shell scripts.
     5  
     6  Dist is itself written in very simple C.  All interaction with C libraries,
     7  even standard C libraries, is confined to a single system-specific file
     8  (plan9.c, unix.c, windows.c), to aid portability.  Functionality needed
     9  by other files should be exposed via the portability layer.  Functions
    10  in the portability layer begin with an x prefix when they would otherwise
    11  use the same name as or be confused for an existing function.
    12  For example, xprintf is the portable printf.
    13  
    14  By far the most common data types in dist are strings and arrays of
    15  strings.  Instead of using char* and char**, though, dist uses two named
    16  data structures, Buf and Vec, which own all the data they point at.
    17  The Buf operations are functions beginning with b; the Vec operations
    18  are functions beginning with v.  The basic form of any function declaring
    19  Bufs or Vecs on the stack should be
    20  
    21  	void
    22  	myfunc(void)
    23  	{
    24  		Buf b1, b2;
    25  		Vec v1;
    26  		
    27  		binit(&b1);
    28  		binit(&b2);
    29  		vinit(&v1);
    30  		
    31  		... main code ...
    32  		bprintf(&b1, "hello, world");
    33  		vadd(&v1, bstr(&b1));  // v1 takes a copy of its argument
    34  		bprintf(&b2, "another string");
    35  		vadd(&v1, bstr(&b2));  // v1 now has two strings
    36  		
    37  		bfree(&b1);
    38  		bfree(&b2);
    39  		vfree(&v1);
    40  	}
    41  	
    42  The binit/vinit calls prepare a buffer or vector for use, initializing the 
    43  data structures, and the bfree/vfree calls free any memory they are still
    44  holding onto.  Use of this idiom gives us lexically scoped allocations.
    45