How to create a shared go module and use it in other projects.

Intro

There is three main ways to setup and use shared libraries in Go. You can either: - Use go workspaces. (link n°1) - Write your code/modules in the `$GOPATH/src` folder, thus you'll have access to all the installed packages. (link n°2) - Write your shared go modules under the same parent directory. (link n°3) - Host your go modules in github or gitlab, so as other users can use `$ go get` to download them. (link n°4)

(NOTE): This guide focuses on the third approach (link n°3), since this helps centralize the code under one parent directory which makes it easier to edit and manage.

Walkthrough

Creating the shared module

Let's assume that we are in our home folder and we have a directory named project where our main project code resides.

    # home/username
        .
        └── project/

From this project we want to access an external library that we will call extrnlib. To do so, start by creating a directory named extrnlib in the home directory. Thus, project/ and externlib/ will be siblings.

    # home/username
        .
        ├── extrnlib/
        └── project/

Go into the externlib and declare it as a go module.

    cd extrnlib/

    # declare this directory as a go module
    go mod init example.com/extrnlib
    > go: creating new go.mod: module example.com/extrnlib

    # verify that the go mod file is proprely created.
    ls 
    > go.mod

Now that we have our shared library module setup, we can go ahead and create our go file where we will export/expose our utility functions. As an example, we will export a function through a lib.go file.

    pwd 
    > /home/username/extrnlib

    touch lib.go

We will add the following code to `lib.go`

    package extrnlib

    func GetLibName() string {
        return "extrnlib-v1.0"
    }

That is pretty much it for our externlib, all that is remaining is to import it and use it in our project.

(NOTE): To avoid any hustles down the road, you can edit the go.mod file so as the mentionned go version is set to the same version as in the project/go.mod file. Do not forget to run a $ go mod tidy after changing the go.mod file.

Importing and using the shared module

In our project/ we should already have a main.go and a go.mod file.

The goal is to use the lib.go declared functions & constructs in our main.go file.

    pwd 
    > home/username/project

    ls 
    > go.mod        main.go

To do so, start by importing and using the extrnlib inside the main.go.

    package main

    import (
        "fmt"
        "example.com/extrnlib"
    )

    func main() {
        fmt.Println(extrnlib.GetLibName())
    }

At this point, the code is correct, but `go` is not able to find the `example.com/extrnlib` package since it is not installed or found under `$GOPATH/src`. Besides, since the `extrnlib` is a local library, it can not be downloaded using `$ go get`. So do not let `gofmt` refactor your code for now.

To make go happy, we will inform it that the extrnlib is a local library/module through the go mod edit -replace command.

    pwd
    > /home/username/project

    go mod edit -replace example.com/extrnlib=../extrnlib

After that command, verify that a new line, as the one below, is added to your `go.mod` file.

    # inside the /home/username/project/go.mod file
    ...

    replace example.com/extrnlib => ../extrnlib
    ...

If all set, we will update the go packages indexing by running $ go mod tidy.

    go mod tidy 
    > go: found example.com/extrnlib in example.com/extrnlib v0.0.0-00010101000000-000000000000

*A similar line should be added to the `go.mod` file as well.*

Now, you can go ahead an run your main.go file inside the project/ directory.

    pwd
    > /home/username/project

    go run main.go
    > extrnlib-v1.0

MassiGy/How to create a shared go module and use it in other projects.md

How to create a shared go module and use it in other projects.

Intro

Walkthrough

Creating the shared module

Importing and using the shared module

Useful links: