• Stars
    star
    1,311
  • Rank 35,893 (Top 0.8 %)
  • Language
    Go
  • License
    MIT License
  • Created over 7 years ago
  • Updated almost 5 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Virtualgo: Easy and powerful workspace based development for go

virtualgo Build Status codecov Go Report Card

Virtualgo (or vg for short) is a tool which provides workspace based development for Go. Its main feature set that makes it better than other solutions is as follows:

  1. Extreme ease of use
  2. No interference with other go tools
  3. Version pinning for imports
  4. Version pinning for executables, such as linters (e.g. errcheck) and codegen tools (e.g. protoc-gen-go)
  5. Importing a dependency that's locally checked out outside of the workspace (also called multi project workflow)
  6. Optional full isolation for imports, see the section on import modes for details.

Virtualgo doesn't do dependency resolution or version pinning itself, because this is a hard problem that's already being solved by other tools. Its approach is to build on top of these tools, such as dep, to provide the features features listed above. For people coming from Python vg is very similar to virtualenv, with dep being respective to pip. The main difference is that vg is much easier to use than virtualenv, because there's almost no mental overhead in using vg.

Go Modules

The Go community is now using Go Modules to handle dependencies. This project is now mostly unmaintained. Please read more about this here.

Example usage

Below is an example showing some basic usage of vg. See further down and vg help for more information and examples.

$ cd $GOPATH/src/github.com/GetStream/example
$ vg init  # initial creation of workspace

# Now all commands will be executed from within the example workspace
(example) $ go get github.com/pkg/errors # package only present in workspace
(example) $ vg ensure  # installs the dependencies of the example project using dep
(example) $ vg deactivate

$ cd ~
$ cd $GOPATH/src/github.com/GetStream/example
(example) $ # The workspace is now activated automatically after cd-ing to the project directory

Advantages over existing solutions

The obvious question is: Why should you use vg? What advantages does it bring over what you're using now? This obviously depends on what you're using now:

Advantages over vendor directory

  1. You can pin versions of executable dependencies, such as linting and code generation tools.
  2. No more issues with go test ./... running tests in the vendor directory when using go 1.8 and below.
  3. You can easily use a dependency from your global GOPATH inside your workspace, without running into confusing import errors.
  4. It has optional full isolation. If enabled there's no accidental fallbacks to regular GOPATH causing confusion about what version of a package you're using.
  5. When using full isolation, tools such as IDEs can spend much less time on indexing. This is simply because they don't have to index the packages outside the workspace.
  6. You don't have problems when using plugins: https://github.com/akutz/gpd

Advantages over manually managing multiple GOPATHs

  1. Automatic activation of a GOPATH when you cd into a directory.
  2. Integration with version management tools such as dep and glide allow for reproducible builds.
  3. Useful commands to manage installed packages. For instance for uninstalling a package or installing a local package from another GOPATH.

Installation

First install the package:

go get -u github.com/GetStream/vg

Although not required, it is recommended to install bindfs as well. This gives the best experience when using full isolation and when using vg localInstall. If you do this, DON'T remove things manually from ~/.virtualgo. Only use vg destroy/vg uninstall, otherwise you can very well lose data.

# OSX
brew install bindfs
# Ubuntu
apt install bindfs
# Arch Linux
pacaur -S bindfs  # or yaourt or whatever tool you use for AUR

Automatic shell configuration

You can run the following command to configure all supported shells automatically:

vg setup

After this you have to reload (source) your shell configuration file:

source ~/.bashrc                   # for bash
source ~/.zshrc                    # for zsh
source ~/.config/fish/config.fish  # for fish

Manual shell configuration

You can also edit your shell configuration file manually. Afterwards you still have to source the file like explained above.

For bash put this in your ~/.bashrc file:

command -v vg >/dev/null 2>&1 && eval "$(vg eval --shell bash)"

Or for zsh, put his in your ~/.zshrc file:

command -v vg >/dev/null 2>&1 && eval "$(vg eval --shell zsh)"

Or for fish, put this in your ~/.config/fish/config.fish file:

command -v vg >/dev/null 2>&1; and vg eval --shell fish | source

Usage

The following commands are the main commands to use vg:

# The first command to use is the one to create and activate a workspace named
# after the current direcory
$ cd $GOPATH/src/github.com/GetStream/example
$ vg init
(example) $
# This command also links the current directory to the created workspace. This
# way the next time you cd to this directory the workspace will be activated
# automatically.
# (See below in the README on how to use the workspace from an IDE)

# All go commands in this shell are now executed from within your workspace. The
# following will install the most recent version of the cobra command and
# library inside the workspace
(example) $ go get -u github.com/spf13/cobra/cobra
(example) $ cobra
Cobra is a CLI library for Go that empowers applications.
......

# It's also possible to only activate a workspace and not link it to the
# current directory. If the workspace doesn't exist it will also be
# created on the fly. Activating a new workspace automatically deactivates
# a previous one:
(example) $ vg activate example2
(example2) $ cobra
bash: cobra: command not found

# To deactivate the workspace simply run:
(example2) $ vg deactivate
$ vg activate
(example) $

# When a workspace is active, a go compilation will try to import packages
# installed from the workspace first. In some cases you might want to use the
# version of a package that is installed in your global GOPATH though. For
# instance when you are fixing a bug in a dependency and want to test the fix.
# In these cases you can easily install a package from your global GOPATH
# into the workspace:
(example) $ vg localInstall github.com/GetStream/utils
# You can even install a package from a specific path:
(example) $ vg localInstall github.com/GetStream/utils ~/weird/path/utils

# You can also uninstall a package from your workspace again
(example) $ vg uninstall github.com/spf13/cobra
# NOTE: At the moment this only removes the sources and static libs in pkg/, not
# executables. So the cobra command is still available.

# See the following sections for integration with dependency management tools.
# And for a full overview of all commands just run:
(example) $ vg help
# For detailed help of a specific command run:
(example) $ vg help <command>

dep integration

vg integrates well with dep (https://github.com/golang/dep):

# Install the dependencies from Gopkg.lock into your workspace instead of the
# vendor directory
vg ensure

# Pass options to `dep ensure`
vg ensure -- -v -update

It also extends dep with a way to install executable dependencies. The vg repo itself uses it to install the go-bindata and cobra command. It does this by adding the following in Gopkg.toml:

required = [
    'github.com/jteeuwen/go-bindata/go-bindata',
    'github.com/spf13/cobra/cobra'
]

Running vg ensure after adding this will install the go-bindata and cobra command in the GOBIN of the current workspace.

As you just saw vg reuses the required list from dep. However, if you don't want to install all packages in the required list you can achieve that by putting the following in Gopkg.toml:

[metadata]
install-required = false

You can also specify which packages to install without the required list:

[metadata]
install = [
    'github.com/jteeuwen/go-bindata/go-bindata',
    'github.com/golang/mock/...', # supports pkg/... syntax
]

Integration with other dependency management tools (e.g glide)

Even though dep is the main tool that virtualgo integrates with. It's also possible to use other dependency management tools instead, as long as they create a vendor directory. Installing executable dependencies is not supported though (PRs for this are welcome).

To use vg with glide works like this:

# Install dependencies into vendor with glide
glide install

# Move these dependencies into the workspace
vg moveVendor

Workspace import modes

A workspace can be set up in two different import modes, global fallback or full isolation. The import mode of a workspace determines how imports from code behave and it is chosen when the workspace is created.

Global fallback

In global fallback mode, packages are imported from the original GOPATH when they are not found in the workspace. This is the default import mode for newly created workspaces, as this interferes the least with existing go tools.

Full isolation

In full isolation mode, package imports will only search in the packages that are installed inside the workspace. This has some advantages:

  1. Tools such as IDE's don't have to search the global GOPATH for imports, which can result in a significant speedup for operations such as indexing.
  2. You always know the location of an imported package.
  3. It's not possible to accidentally import of a package that is not managed by your vendoring tool of choice.

However, there's also some downsides to full isolation of a workspace. These are all caused by the fact that the project you're actually working on is not inside your GOPATH anymore. So normally go would not be able to find any imports to it. This is partially worked around by locally installing the project into your workspace, but it does not fix all issues.

In the sections below the remaining issues are described and you can decide for yourself if the above advantages are worth the disadvantages. If you want to try out full isolation you can create a new workspace using the --full-isolation flag:

$ vg init --full-isolation
# To change an existing workspace, you have to destroy and recreate it
$ vg destroy example
$ vg activate example --full-isolation

This will cause the workspace to use full isolation import mode each time it is activated in the future. So there's no need to specify the --full-isolation flag on each activation afterwards.

With bindfs installed

If you have bindfs installed the issues you will run into are only a slight inconvenience, for which easy workarounds exist. However, it is important that you know about them, because they will probably cause confusion otherwise. If you run into any other issues than the ones mentioned here, please report them.

Relative packages in commands

The first set of issues happen when using relative reference to packages in commands. Some examples of this are:

  • go list ./... will return weirdly formatted paths, such as _/home/stream/go/src/github.com/GetStream/vg.
  • go test ./..., might cause an init function to be executed twice.
  • go build ./... won't work when an internal package is present in the directory. Here you can expect an error saying use of internal package not allowed.

Luckily, this can all easily be worked around by using absolute package paths for these commands. So for the vg repo you would use the following alternatives:

# go list ./...
go list github.com/GetStream/vg/...
# go test ./...
go test github.com/GetStream/vg/...
# go build ./...
go build github.com/GetStream/vg/...
dep commands

Another issue that pops up is that dep doesn't allow it's commands to be executed outside of the GOPATH. This is not a problem for dep ensure, since you usually use vg ensure, which handles this automatically. However, this is an issue for other commands, such as dep status and dep init. Luckily there's an easy workaround for this as well. You can simply use vg globalExec, to execute commands from your regular GOPATH, which fixes the issue:

vg globalExec dep init
vg globalExec dep status

Without bindfs installed

If bindfs is not installed, symbolic links will be used to do the local install. This has the same issues as described for bindfs, but there's also some extra ones that cannot be worked around as easily. The reason for this is that go tooling does not like symbolic links in GOPATH (golang/go#15507, golang/go#17451).

Compiling will still work, but go list github.com/... will not list your package. Other than that there are also issues when using delve (#11). Because of these issues it is NOT RECOMMENDED to use virtualgo in full isolation mode without bindfs installed.

Using a virtualgo workspace with an IDE (e.g. GoLand)

Because virtualgo is just a usability wrapper around changing your GOPATH for a specific project it is usually quite easy to use it in combination with an IDE. Just check out your GOPATH after activating a workspace and configure the IDE accordingly. Usually if you show your GOPATH you will see two paths separated by a colon:

$ echo $GOPATH
/home/stream/.virtualgo/myworkspace:/home/stream/go

If you can set this full string directly that is fine. For GoLand you have to add the first one first and then the second one.

When using a workspace in full isolation mode it's even easier to set up as there's only one GOPATH set.

$ echo $GOPATH
/home/stream/.virtualgo/myworkspace

License

MIT

Careers @ Stream

Would you like to work on cool projects like this? We are currently hiring for talented Gophers in Amsterdam and Boulder, get in touch with us if you are interested! [email protected]

More Repositories

1

Winds

A Beautiful Open Source RSS & Podcast App Powered by Getstream.io
JavaScript
8,813
star
2

stream-chat-android

💬 Android Chat SDK ➜ Stream Chat API. UI component libraries for chat apps. Kotlin & Jetpack Compose messaging SDK for Android chat
Kotlin
1,443
star
3

whatsApp-clone-compose

📱 WhatsApp clone project demonstrates modern Android development built with Jetpack Compose and Stream Chat/Video SDK for Compose.
Kotlin
1,254
star
4

stream-react-example

Use React and Redux to build your own feature-rich and scalable social network app! Visit cabin.getstream.io for an overview of all 8 tutorials and a live demo.
HTML
923
star
5

stream-chat-flutter

Flutter Chat SDK - Build your own chat app experience using Dart, Flutter and the Stream Chat Messaging API.
Dart
839
star
6

stream-chat-react-native

💬 React-Native Chat SDK ➜ Stream Chat. Includes a tutorial on building your own chat app experience using React-Native, React-Navigation and Stream
TypeScript
792
star
7

purposeful-ios-animations

Meaningful iOS animations built to inspire you in creating useful animations for your apps. Each of the animations here was cloned with SwiftUI. Have you seen an app animation you love to rebuild and add to this repo?, contact [@amos_gyamfi](https://twitter.com/amos_gyamfi) and [@stefanjblos](https://twitter.com/stefanjblos) on Twitter.
Swift
763
star
8

stream-chat-swift

💬 iOS Chat SDK in Swift - Build your own app chat experience for iOS using the official Stream Chat API
Swift
750
star
9

swiftui-spring-animations

This repository serves as your reference and complete guide for SwiftUI Spring Animations. It demonstrates use cases for the various types of spring animations and spring parameters. No more guessing the values of the parameters for spring animations you create for your next iOS app.
Swift
692
star
10

webrtc-android

🛰️ A versatile WebRTC pre-compiled Android library that reflects the recent WebRTC updates to facilitate real-time video chat for Android and Compose.
Kotlin
578
star
11

stream-chat-react

React Chat SDK ➜ Stream Chat 💬
TypeScript
552
star
12

awesome-saas-services

A curated list of the best in class SaaS services for developers and business owners.
475
star
13

stream-django

Django Client - Build Activity Feeds & Streams with GetStream.io
Python
453
star
14

sketchbook-compose

🎨 Jetpack Compose canvas library that helps you draw paths, images on canvas with color pickers and palettes.
Kotlin
442
star
15

avatarview-android

✨ Supports loading profile images with fractional styles, shapes, borders, indicators, and initials for Android.
Kotlin
432
star
16

webrtc-in-jetpack-compose

📱 This project demonstrates WebRTC protocol to facilitate real-time video communications with Jetpack Compose.
Kotlin
402
star
17

stream-video-android

📲 Android Video SDK. Stream's versatile Core + Compose UI component libraries that allow you to build video calling, audio room, and, live streaming apps based on Webrtc running on Stream's global edge network.
Kotlin
374
star
18

AvengersChat

💙 Android sample Avengers chat application using Stream Chat SDK based on MVVM (ViewModel, Coroutines, Room, Hilt, Repository) architecture.
Kotlin
367
star
19

stream-draw-android

🛥 Stream Draw is a real-time multiplayer drawing & chat game app built entirely with Jetpack Compose.
Kotlin
341
star
20

stream-chat-swiftui

SwiftUI Chat SDK ➜ Stream Chat 💬
Swift
329
star
21

stream-js

JS / Browser Client - Build Activity Feeds & Streams with GetStream.io
JavaScript
329
star
22

effects-library

The Effects Library allows developers to create sophisticated and realistic particle systems such as snow, fire, rain, confetti, fireworks, and smoke with no or minimal effort.
Swift
324
star
23

react-native-example

React Native Activity Feed example application
JavaScript
321
star
24

stream-laravel

Laravel Client - Build Activity Feeds & Streams with GetStream.io
PHP
314
star
25

flutter-samples

A collection of sample apps that use Stream
Dart
298
star
26

stream-rails

Rails Client - Build Activity Feeds & Streams with GetStream.io
Ruby
257
star
27

Streamoji

:godmode: Custom emoji rendering library for iOS apps with support for GIF & still images - plug-in extension for UITextView - performance, cache ✅ - Made with 💘 by @GetStream
Swift
248
star
28

react-native-bidirectional-infinite-scroll

📜 React Native - Bidirectional Infinite Smooth Scroll
TypeScript
220
star
29

WhatsApp-Clone-Android

Tutorial which teaches you how to build a whatsapp chat clone on android using Kotlin, viewmodels, navigation component and Stream
Kotlin
218
star
30

butterfly

🦋 Butterfly helps you to build adaptive and responsive UIs for Android with Jetpack WindowManager.
Kotlin
214
star
31

slack-clone-react-native

Build a slack clone using react-native, Stream and react-navigation
JavaScript
206
star
32

react-native-activity-feed

Official React Native SDK for Activity Feeds
JavaScript
194
star
33

motionscape-app

MotionScape is your animations playground as a developer. You can see all animations and their parameters in effect with beautifully designed and handcrafted animation examples.
Swift
167
star
34

Android-Samples

📕 Provides a list of samples that utilize modern Android tech stacks and Stream Chat SDK for Android and Compose.
Kotlin
159
star
35

node-express-mongo-api

Starter project for a REST API with Node.js, Express & MongoDB 🔋
JavaScript
151
star
36

stream-chat-js

JS / Browser Client - Build Chat with GetStream.io
TypeScript
149
star
37

meeting-room-compose

🎙️ A real-time meeting room app built with Jetpack Compose to demonstrate video communications.
Kotlin
141
star
38

stream-php

PHP Client - Build Activity Feeds & Streams with GetStream.io
PHP
139
star
39

stream-log

🛥 Stream Log is a lightweight and extensible logger library for Kotlin Multiplatform.
Kotlin
136
star
40

react-activity-feed

Stream React Activity Feed Components
TypeScript
136
star
41

stream-python

Python Client - Build Activity Feeds & Streams with GetStream.io
Python
136
star
42

flat-list-mvcp

"maintainVisibleContentPosition" prop support for Android react-native
TypeScript
133
star
43

stream-node-orm

NodeJS Client - Build Activity Feeds & Streams with GetStream.io
JavaScript
131
star
44

website-react-examples

TypeScript
122
star
45

stream-video-swift

SwiftUI Video SDK ➡️ Stream Video 📹
Swift
117
star
46

react-native-samples

A collection of sample apps built using GetStream and React Native
JavaScript
116
star
47

flutter-instagram-clone

An Instagram clone using Flutter and Stream Feeds
Dart
111
star
48

django_twitter

An example app built using getstream.io
Python
108
star
49

twitter-clone

Learn how to build a functional Twitter clone using Stream, 100ms, Algolia, RevenueCat and Mux 😎
Swift
107
star
50

accessible-inclusive-ios-animations

Provide ways to limit animations/motion people find jarring in your apps. This repo demonstrates accessible and inclusive iOS animations/motion with practical examples and best practices.
Swift
107
star
51

stream-result

🚊 Railway-oriented library to easily model and handle success/failure for Kotlin Multiplatform.
Kotlin
102
star
52

Stream-Example-Nodejs

An example app built using getstream.io
JavaScript
96
star
53

Android-Video-Samples

📘 Provides a collection of samples that utilize modern Android tech stacks and Stream Video SDK for Kotlin and Compose.
Kotlin
88
star
54

react-native-audio-player

JavaScript
86
star
55

stream-ruby

Ruby Client - Build Activity Feeds & Streams with GetStream.io
Ruby
83
star
56

stream-tutorial-projects

This repo contains SwiftUI, Jetpack Compose, JS & React Native projects for some of the iOS and Android tutorial series in the Stream Developers YouTube channel (https://youtube.com/playlist?list=PLNBhvhkAJG6tJYnY-5oZ1JCp2fBNbVL_6).
Swift
83
star
57

stream-chat-unity

💬 Unity Chat Plugin by Stream ➜ These assets are the solution for adding an in-game text chat system to your Unity game.
C#
83
star
58

stream-go2

GetStream.io Go client
Go
82
star
59

stream-cli

Configure & manage Stream applications from the command line. 🚀
Go
80
star
60

mongodb-activity-feed

Activity Feed, Timeline, News Feed, Notification Feed with MongoDB, Node and CRDTs
JavaScript
77
star
61

android-video-chat

⚡️ Android Video Chat demonstrates a real-time video chat application by utilizing Stream Chat & Video SDKs.
Kotlin
76
star
62

TinyGraphQL

🌸 Simple and lightweight GraphQL query builder for the Swift language - Made with 💘 by @GetStream
Swift
76
star
63

slack-clone-expo

Slack clone using Expo, Stream and react-navigation
JavaScript
75
star
64

liveshopping-android

📹 A demo app showcasing real-time livestreaming and messaging capabilities built with Jetpack Compose and Stream SDKs.
Kotlin
74
star
65

fullstack-nextjs-whatsapp-clone

A sample codebase showcasing Stream Chat and Video to resembling WhatsApp, using NextJS, TailwindCSS and Vercel.
TypeScript
72
star
66

stream-feed-flutter

Stream Feed official Flutter SDK. Build your own feed experience using Dart and Flutter.
Dart
69
star
67

stream-chat-go

Stream Chat official Golang API Client
Go
67
star
68

stream-video-js

GetStream JavaScript Video SDK
TypeScript
66
star
69

discord-clone-nextjs

Building a discord clone using NextJS, TailwindCSS, and the Stream Chat and Audio and Video SDKs.
TypeScript
64
star
70

SwiftUIMessagesUIClone

The SwiftUI Messages Clone consists of layout and composition clones of the iOS Messages app. It has Messages-like bubble and screen effects, reactions, and animations, all created with SwiftUI.
Swift
62
star
71

Stream-Example-Py

An example app built using getstream.io
CSS
61
star
72

encrypted-web-chat

A web chat application end-to-end encrypted with the Web Crypto API
JavaScript
59
star
73

swift-lambda

λ Write HTTP services in Swift, deploy in seconds - Powered by AWS Lambda Runtime & Serverless Framework - Made with 💘 by @GetStream
Swift
57
star
74

stream-chat-python

Stream Chat official Python API Client
Python
56
star
75

stream-java

Java Client - Build Activity Feeds & Streams with GetStream.io
Java
53
star
76

stream-video-flutter

Flutter Video SDK - Build your own video app experience using Dart, Flutter and the Stream Video Messaging API.
Dart
46
star
77

Stream-Example-Parse

Stream-Example-Parse
JavaScript
46
star
78

Stream-Example-PHP

An example app built using getstream.io https://getstream.io
PHP
46
star
79

android-chat-tutorial

Sample apps for the Stream Chat Android SDK's official tutorial
Java
46
star
80

stream-meteor

Meteor Client - Build Activity Feeds & Streams with GetStream.io
JavaScript
45
star
81

SwiftUIChristmasTree

🌲 Pure SwiftUI christmas tree with yearly updates. Enjoy 🎄
Swift
45
star
82

python-chat-example

Chat with Python, Django and React
JavaScript
44
star
83

stream-chat-net

Stream Chat official .NET API Client
C#
43
star
84

stream-chat-dart

Dart SDK - Build Chat with GetStream.io
Dart
42
star
85

kmp-sample-template

A minimal Kotlin & Compose Multiplatform template designed to build applications for both Android and iOS.
Kotlin
41
star
86

Stream-Example-Go-Cassandra-API

Go-powered API example using Cassandra
Go
38
star
87

Stream-Example-Rails

An example app built using getstream.io
Ruby
38
star
88

Stream-Example-Android

Java
38
star
89

foldable-chat-android

🦚 Foldable chat Android demonstrates adaptive and responsive UIs with Jetpack WindowManager API.
Kotlin
35
star
90

stream-net

NET Client - Build Activity Feeds & Streams with GetStream.io
C#
35
star
91

stream-swift

Swift client for Stream API
Swift
35
star
92

stream-chat-angular

💬 Angular Chat SDK ➜ Stream Chat. Build a chat app with ease.
TypeScript
34
star
93

SwiftUI-open-voip-animations

SwiftUI animations and UI designs for iOS calling, meeting, audio-room, and live streaming use cases. Find something missing? Let @amos_gyamfi know on Twitter.
33
star
94

node-restify-mongo-api

Starter project for a REST API with Node.js, Restify & MongoDB 🔋
JavaScript
32
star
95

stream-chat-unreal

The official Unreal SDK for Stream Chat
C++
32
star
96

build-viking-sample

Sample app for Build Viking.
Dart
31
star
97

swiftui-iMessage-clone

Swift
30
star
98

swift-activity-feed

Stream Swift iOS Activity Feed Components
Swift
29
star
99

stream-chat-ruby

Stream Chat official Ruby API Client
Ruby
29
star
100

sign-in-with-apple-swift-example

iOS + Node.js authentication using Sign in with Apple
Swift
28
star