mediocregopher/ginger
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
55ecdc9f2a
ginger/docs/compilation.md
Brian Picciano 0fdb7f1af5 move docs into docs
2014-10-06 17:44:07 -04:00

4.2 KiB
Raw Blame History

Hello world

The following code in a file called hello-world.gg can be compiled to a static binary which will output "Hello World!" and exit:

(. package "github.com/mediocregopher/ginger-hello-world"
    (. defn main []
        (: fmt.Println "Hello World!"))
)

While in the same directory as hello-world.gg, this can be compiled and run with:

ginger run

and built into a static binary with:

ginger build

package

The package string defines where in the namespace tree this file belongs. Code in this file can directly reference variables, private or public, from other files in the same package.

The physical layout of the files is not consequential, ginger only cares what package they say they belong to, it's not required that the directory tree matches the namespace tree.

main

Every executable which ginger compiles needs one main function to use as the entrypoint. Ginger looks for a main function in all the .gg files in the current working directory in order to compile. If it finds one it uses that, if it finds zero or more than one it errors and tells the user they need to specify either a package or file name.

Compilation

Ginger is first compiled into go code, and the subsequently uses the go tool to compile that code into a static binary. Because of this ginger is able to use any code from the go standard library, as well as any third-party go libraries which may want to be used.

Ginger takes advantage of the GOPATH when compiling in order to find packages. Upon starting up ginger will set the GOPATH as follows for the duration of the run:

GOPATH=./target:$GOPATH

The following steps are then taken for compilation:

  • Create a folder in the cwd called target, if it isn't already there. Also create a src subfolder inside of that.

  • Scan the cwd and any subdirectories (including target) for .gg files. Translate them into .go files and place them according to their package name in the target/src directory. So if a file has a package github.com/mediocregopher/foobar it would be compiled and placed as target/src/github.com/mediocregopher/foobar/file.go. The main function is found and the package for it is determined in this step as well.

  • As the cwd .gg files are scanned a set of packages which are required is built. If any are not present in target at the end of the last step and are not present as go projects in the GOPATH then they are searched for as ginger projects in the GOPATH. Packages found will be translated into the target directory (very important, this prevents the global GOPATH from getting cluttered with tranlated .go files which aren't actually part of the project). This step is repeated until all dependencies are met, or until they're not and an error is thrown.

  • At this point all necessary .go files to build the project are present in the GOPATH (global or target). go build is called on the main package and output to the target directory.

Properties

Given those compilation steps ginger has the following properties:

  • Dependencies for a ginger project, either go or ginger, can be installed globally or to the target folder (sandboxed) by a dependency management tool (probably built into ginger).

  • It is easy to find exactly what your code is being translated to since it will always be in the target directory.

  • Translated code will not clutter up the global GOPATH.

  • Only the target directory needs to be added to a .gitignore file.

  • Some amount of ginger-to-ginger monkey patching may be possible. Not sure if this is a good or bad thing.

  • Compilation may take a while. There is some amount of hunting for .gg files required, and all found ones must be compiled even if they're not going to be used, since package names can be arbitrarily stated. There are some ways to help this:

    • Might be worth taking a shortcut like grepping through all files in the GOPATH for the package string only compiling the ones which pass the grep.

    • Put placeholder .go files in the target directory to indicate that the package isn't needed for subsequent installs. Not the best idea, since changes to the dependency list in the project may not correctly process.