README
¶
Matcha - iOS apps in Go
Matcha is in early development! There are many rough edges and APIs may still change. Please file issues for any bugs you find.
What is Matcha?
Matcha is a package for building iOS applications and frameworks in Go. Matcha provides a UI compenent library similar to ReactNative and exposes bindings to Objective-C code through reflection. The library also provides Go APIs for common app tasks. Matcha makes it easy to build complex mobile apps and integrate with existing projects.
Examples
Getting Started
Matcha requires macOS, Xcode 8.3 and Go 1.8. To start, fetch the project and install the matcha command.
go get gomatcha.io/matcha/...
Now we build the standard library for the device and the simulator with the following command. The output is installed at $GOPATH/pkg/matcha. If your path doesn't contain $GOPATH/bin, you may need to replace these calls with $GOPATH/bin/matcha.
matcha init
With this in place, build the example project. The output is installed at $GOPATH/src/gomatcha.io/matcha/ios/MatchaBridge/MatchaBridge/MatchaBridge.a.
matcha build gomatcha.io/matcha/examples
Thats it! We can now open the example Xcode project and run the app! You may also need to set the Development Team under General > Signing.
open $GOPATH/src/gomatcha.io/matcha/examples/ios-app/SampleApp.xcworkspace
Tutorial
Here we will walk you through the steps for building a simple Hello World app. It assumes basic knowledge of iOS and Go development. Please go through the Getting Started guide if you have not already done so.
Crate a directory for your app in your $GOPATH.
mkdir -p $GOPATH/src/github.com/overcyn/tutorial
Now create a Xcode workspace in this directory and add the projects found in $GOPATH/src/gomatcha.io/matcha/ios/. There are 3 projects, Matcha, MatchaBridge, and Protobuf. You can do this by dragging the projects into your workspace. At this point you should be able to build the Matcha.framework.
Create a new Xcode project containing a Single View Application in your directory, and add it to the workspace.
Your workspace should now enclose 4 projects. We now need to make some changes to the Xcode project settings.
- Select your development team in General > Signing > Team.
- Disable Bitcode in Build Settings > Build Settings > Enable Bitcode.
- Link and copy in frameworks in Build Phases > Link Binaries with Libraries and Build Phases > Copy Files.
Thats all the setup thats needed, now to start writing code! Create a new go file in the directory with the following snippet. This is a lot to take in at once, but we'll try to go through it step by step in the comments.
package tutorial
import (
"golang.org/x/image/colornames"
"gomatcha.io/matcha/layout/constraint"
"gomatcha.io/matcha/paint"
"gomatcha.io/matcha/text"
"gomatcha.io/matcha/view"
"gomatcha.io/matcha/view/textview"
)
// Here is our root view.
type TutorialView struct {
// All components must implement the view.View interface. A basic implementation
// is provided by view.Embed.
view.Embed
}
// This is our view's initializer.
func New(ctx *view.Context, key string) *TutorialView {
// To prevent rebuilding the entire tree on every rerender, initializers will return
// the previous view if it already exists. Most views will contain this bit
// of boilerplate.
if v, ok := ctx.Prev(key).(*TutorialView); ok {
return v
}
// If there was no matching view, we create a new one.
return &TutorialView{Embed: ctx.NewEmbed(key)}
}
// Similar to React's render function. Views specify their properties and
// children in Build().
func (v *TutorialView) Build(ctx *view.Context) view.Model {
l := &constraint.Layouter{}
// Get the textview for the given key (hellotext), either initializing it or fetching
// the previous one.
textv := textview.New(ctx, "hellotext")
textv.String = "Hello World"
textv.Style.SetTextColor(colornames.Red)
textv.Style.SetFont(text.Font{
Family: "Helvetica Neue",
Face: "Bold",
Size: 50,
})
textv.PaintStyle = &paint.Style{BackgroundColor: colornames.Blue}
// Layout is primarily done using a constraints. More info can be
// found in the matcha/layout/constraints docs.
l.Add(textv, func(s *constraint.Solver) {
s.Top(20)
s.Left(0)
})
// Returns the view's children, layout, and styling.
return view.Model{
Children: []view.View{textv},
Layouter: l,
Painter: &paint.Style{BackgroundColor: colornames.Lightgray},
}
}
Now that we have our view in Go, we need to be call it from Objective C. We can do this with the gomatcha.io/bridge package.
import "gomatcha.io/bridge"
func init() {
// Registers a function with the objc bridge. This function returns
// a view.Root, which can be display in MatchaViewController.
bridge.RegisterFunc("github.com/overcyn/tutorial New", func() *view.Root {
// Call the TutorialView initializer.
return view.NewRoot(New(nil, ""))
})
}
Build the Go code.
matcha build github.com/overcyn/tutorial
Now for the Objective C code. Add imports for Matcha in AppDelegate.m.
#import <Matcha/Matcha.h>
And replace application:didFinishLaunchingWithOptions: with the following.
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
MatchaGoValue *rootVC = [[[MatchaGoValue alloc] initWithFunc:@"github.com/overcyn/tutorial New"] call:nil args:nil][0];
self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
self.window.rootViewController = [[MatchaViewController alloc] initWithGoValue:rootVC];
[self.window makeKeyAndVisible];
return YES;
}
And run your application! Well done!
FAQ
Is there Bitcode support?
Bitcode is an LLVM feature that is not supported by Go at this time.
What are other similar libaries?
Documentation
¶
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package animate implements animations, easings and interpolaters.
|
Package animate implements animations, easings and interpolaters. |
|
Package keyboard exposes access to displaying and hiding the keyboard.
|
Package keyboard exposes access to displaying and hiding the keyboard. |
|
absolute
Package absolute implements a fixed layout system similar to HTML absolute positioning.
|
Package absolute implements a fixed layout system similar to HTML absolute positioning. |
|
constraint
Package constraint implements a constraint-based layout system.
|
Package constraint implements a constraint-based layout system. |
|
full
Package full implements a layout system where the view and all direct children are positioned to the maximum size.
|
Package full implements a layout system where the view and all direct children are positioned to the maximum size. |
|
table
Package table implements a vertical, single column layout system.
|
Package table implements a vertical, single column layout system. |
|
Package paint implements view display properties.
|
Package paint implements view display properties. |
|
Package pb is a generated protocol buffer package.
|
Package pb is a generated protocol buffer package. |
|
app
Package app is a generated protocol buffer package.
|
Package app is a generated protocol buffer package. |
|
env
Package env is a generated protocol buffer package.
|
Package env is a generated protocol buffer package. |
|
keyboard
Package keyboard is a generated protocol buffer package.
|
Package keyboard is a generated protocol buffer package. |
|
layout
Package layout is a generated protocol buffer package.
|
Package layout is a generated protocol buffer package. |
|
paint
Package paint is a generated protocol buffer package.
|
Package paint is a generated protocol buffer package. |
|
text
Package text is a generated protocol buffer package.
|
Package text is a generated protocol buffer package. |
|
touch
Package touch is a generated protocol buffer package.
|
Package touch is a generated protocol buffer package. |
|
view
Package view is a generated protocol buffer package.
|
Package view is a generated protocol buffer package. |
|
view/alert
Package alert is a generated protocol buffer package.
|
Package alert is a generated protocol buffer package. |
|
view/button
Package button is a generated protocol buffer package.
|
Package button is a generated protocol buffer package. |
|
view/imageview
Package imageview is a generated protocol buffer package.
|
Package imageview is a generated protocol buffer package. |
|
view/progressview
Package progressview is a generated protocol buffer package.
|
Package progressview is a generated protocol buffer package. |
|
view/scrollview
Package scrollview is a generated protocol buffer package.
|
Package scrollview is a generated protocol buffer package. |
|
view/segmentview
Package segmentview is a generated protocol buffer package.
|
Package segmentview is a generated protocol buffer package. |
|
view/slider
Package slider is a generated protocol buffer package.
|
Package slider is a generated protocol buffer package. |
|
view/stacknav
Package stacknav is a generated protocol buffer package.
|
Package stacknav is a generated protocol buffer package. |
|
view/switchview
Package switchview is a generated protocol buffer package.
|
Package switchview is a generated protocol buffer package. |
|
view/tabscreen
Package tabscreen is a generated protocol buffer package.
|
Package tabscreen is a generated protocol buffer package. |
|
view/textinput
Package textinput is a generated protocol buffer package.
|
Package textinput is a generated protocol buffer package. |
|
Package text implements text styling.
|
Package text implements text styling. |
|
Package constraint implements touch recognizers.
|
Package constraint implements touch recognizers. |
|
alert
Package alert implements basic alerts.
|
Package alert implements basic alerts. |
|
basicview
Package basicview implements an empty view.
|
Package basicview implements an empty view. |
|
button
Package button implements a native button view.
|
Package button implements a native button view. |
|
imageview
Package button implements a view that can display an image.
|
Package button implements a view that can display an image. |
|
progressview
Package button implements a native progress view.
|
Package button implements a native progress view. |
|
scrollview
Package button implements a native scroll view.
|
Package button implements a native scroll view. |
|
segmentview
Package segmentview implements a native segmented control.
|
Package segmentview implements a native segmented control. |
|
slider
Package segmentview implements a native slider.
|
Package segmentview implements a native slider. |
|
switchview
Package switchview implements a native switch.
|
Package switchview implements a native switch. |
|
urlimageview
Package urlimageview implements a view which loads and displays an image.
|
Package urlimageview implements a view which loads and displays an image. |