Skip to content

Commit 383fc8b

Browse files
neelanceneelance
committed
updated index page
1 parent 6effede commit 383fc8b

File tree

1 file changed

+56
-41
lines changed

1 file changed

+56
-41
lines changed

‎index.md

Lines changed: 56 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -4,81 +4,96 @@ title: Home
44
permalink: /
55
---
66

7-
Go -> JavaScript
8-
----------------
7+
GopherJS - A compiler from Go to JavaScript
8+
-------------------------------------------
99

1010
GopherJS compiles Go code ([golang.org](http://golang.org/)) to pure JavaScript code. Its main purpose is to give you the opportunity to write front-end code in Go which will still run in all browsers. Give GopherJS a try on the [GopherJS Playground](http://gopherjs.github.io/playground/).
1111

12-
You can take advantage of Go's elegant type system and other compile-time checks that can have a huge impact on bug detection and the ability to refactor, especially for big projects. Just think of how often a JavaScript method has extra handling of some legacy parameter scheme, because you don't know exactly if some other code is still calling it in that old way or not. GopherJS will tell you and if it does not complain, you can be sure that this kind of bug is not present any more.
13-
14-
### Design Goals
15-
- performance of generated code (see [HTML5 game engine benchmark](http://ajhager.github.io/enj/) by Joseph Hager)
16-
- similarity between Go code and generated JavaScript code for easier debugging
17-
- compatibility with existing libraries (see the list of [bindings to JavaScript APIs and libraries](https://github.com/gopherjs/gopherjs/wiki/bindings))
18-
- small size of generated code
19-
2012
### What is supported?
21-
Nearly everything, including Goroutines. See the [compatibility table](//github.com/gopherjs/gopherjs/blob/master/doc/packages.md) for details.
22-
23-
### Goroutines
24-
JavaScript has no concept of concurrency (except web workers, but those are too strictly separated to be used for goroutines). Because of that, instructions in JavaScript are never blocking. A blocking call would effectively freeze the responsiveness of your web page, so calls with callback arguments are used instead.
25-
26-
GopherJS does some heavy lifting to work around this restriction: Whenever an instruction is blocking (e.g. communicating with a channel that isn't ready), the whole stack will unwind (= all functions return) and the goroutine will be put to sleep. Then another goroutine which is ready to resume gets picked and its stack with all local variables will be restored. This is done by preserving each stack frame inside a closure.
27-
28-
The performance of the code generated by this approach is quite good, but not as good as the simple nonblocking version. That's why GopherJS tries to be conservative about it. It will scan your code for functions that use blocking instructions and mark them as blocking accordingly. Then it will recursively mark all functions as blocking which have a call to some other function which is already know to be blocking. This works well for calls to package functions and for method calls on non-interface types. For calls to interface methods and to `func` values, however, it is not exactly known at compile time which function will be executed at runtime. In those cases you need to mark the call with the comment `//gopherjs:blocking` (no space after the slashes). Else, the call will panic at runtime.
29-
30-
Also, callbacks from external JavaScript code into Go code (see below) can never be blocking, but you may use the `go` statement to create a new goroutine that may have blocking behavior.
13+
Nearly everything, including Goroutines ([compatibility table](doc/packages.md)). Performance is quite good in most cases, see [HTML5 game engine benchmark](http://ajhager.github.io/enj/).
3114

3215
### Installation and Usage
3316
Get or update GopherJS and dependencies with:
34-
35-
```bash
17+
```
3618
go get -u github.com/gopherjs/gopherjs
3719
```
38-
39-
Now you can use `gopherjs build [files]` or `gopherjs install [package]` which behave similar to the `go` tool. For `main` packages, these commands create a `.js` file and `.js.map` source map in the current directory or in `$GOPATH/bin`. The generated JavaScript file can be used as usual in a website. Use `gopherjs help [command]` to get a list of possible command line flags, e.g. for minification and automatically watching for changes. If you want to run the generated code with Node.js, see [this page](//github.com/gopherjs/gopherjs/blob/master/doc/syscalls.md).
20+
Now you can use `gopherjs build [files]` or `gopherjs install [package]` which behave similar to the `go` tool. For `main` packages, these commands create a `.js` file and `.js.map` source map in the current directory or in `$GOPATH/bin`. The generated JavaScript file can be used as usual in a website. Use `gopherjs help [command]` to get a list of possible command line flags, e.g. for minification and automatically watching for changes. If you want to run the generated code with Node.js, see [this page](doc/syscalls.md).
4021

4122
*Note: GopherJS will try to write compiled object files of the core packages to your $GOROOT/pkg directory. If that fails, it will fall back to $GOPATH/pkg.*
4223

43-
### Getting started
24+
### Performance Tips
4425

45-
#### 1. Interacting with the DOM
46-
The package `github.com/gopherjs/gopherjs/js` (see [documentation](http://godoc.org/github.com/gopherjs/gopherjs/js)) provides functions for interacting with native JavaScript APIs. For example the line
26+
- Use the `-m` command line flag to generate minified code.
27+
- Apply gzip compression (http://en.wikipedia.org/wiki/HTTP_compression).
28+
- Use `int` instead of `(u)int8/16/32/64`.
29+
- Use `float64` instead of `float32`.
30+
31+
### Community
32+
- [Google Group](https://groups.google.com/d/forum/gopherjs)
33+
- [Bindings to JavaScript APIs and libraries](https://github.com/gopherjs/gopherjs/wiki/bindings)
34+
- [GopherJS on Twitter](https://twitter.com/GopherJS)
4735

36+
### Getting started
37+
#### Interacting with the DOM
38+
The package `github.com/gopherjs/gopherjs/js` (see [documentation](http://godoc.org/github.com/gopherjs/gopherjs/js)) provides functions for interacting with native JavaScript APIs. For example the line
4839
```js
4940
document.write("Hello world!");
5041
```
51-
5242
would look like this in Go:
53-
5443
```go
5544
js.Global.Get("document").Call("write", "Hello world!")
5645
```
57-
5846
You may also want use the [DOM bindings](http://dominik.honnef.co/go/js/dom), the [jQuery bindings](https://github.com/gopherjs/jquery) (see [TodoMVC Example](https://github.com/gopherjs/todomvc)) or the [AngularJS bindings](https://github.com/gopherjs/go-angularjs). Those are some of the [bindings to JavaScript APIs and libraries](https://github.com/gopherjs/gopherjs/wiki/bindings) by community members.
5947

60-
#### 2. Providing library functions for use in other JavaScript code
48+
#### Providing library functions for use in other JavaScript code
6149
Set a global variable to a map that contains the functions:
62-
6350
```go
6451
package main
6552

6653
import "github.com/gopherjs/gopherjs/js"
6754

6855
func main() {
69-
js.Global.Set("myLibrary", map[string]interface{}{
70-
"someFunction": someFunction,
56+
js.Global.Set("pet", map[string]interface{}{
57+
"New": New,
7158
})
7259
}
7360

74-
func someFunction() {
75-
[...]
61+
type Pet struct {
62+
name string
63+
}
64+
65+
func New(name string) *js.Object {
66+
return js.MakeWrapper(&Pet{name})
67+
}
68+
69+
func (p *Pet) Name() string {
70+
return p.name
7671
}
77-
```
7872

73+
func (p *Pet) SetName(name string) {
74+
p.name = name
75+
}
76+
```
7977
For more details see [Jason Stone's blog post](http://legacytotheedge.blogspot.de/2014/03/gopherjs-go-to-javascript-transpiler.html) about GopherJS.
8078

81-
### Community
82-
- Get help in the [Google Group](https://groups.google.com/d/forum/gopherjs)
83-
- See the list of [bindings to JavaScript APIs and libraries](https://github.com/gopherjs/gopherjs/wiki/bindings) by community members
84-
- Follow [GopherJS on Twitter](https://twitter.com/GopherJS)
79+
### Architecture
80+
81+
#### General
82+
GopherJS emulates a 32-bit environment. This means that `int`, `uint` and `uintptr` have a precision of 32 bits. However, the explicit 64-bit integer types `int64` and `uint64` are supported. The `GOARCH` value of GopherJS is "js". You may use it as a build constraint: `// +build js`.
83+
84+
#### Goroutines
85+
Goroutines are fully supported by GopherJS. The only restriction is that you need to start a new goroutine if you want to use blocking code called from external JavaScript:
86+
87+
```go
88+
js.Global.Get("myButton").Call("addEventListener", "click", func() {
89+
go func() {
90+
someBlockingFunction()
91+
}()
92+
})
93+
```
94+
95+
How it works:
96+
97+
JavaScript has no concept of concurrency (except web workers, but those are too strictly separated to be used for goroutines). Because of that, instructions in JavaScript are never blocking. A blocking call would effectively freeze the responsiveness of your web page, so calls with callback arguments are used instead.
98+
99+
GopherJS does some heavy lifting to work around this restriction: Whenever an instruction is blocking (e.g. communicating with a channel that isn't ready), the whole stack will unwind (= all functions return) and the goroutine will be put to sleep. Then another goroutine which is ready to resume gets picked and its stack with all local variables will be restored. This is done by preserving each stack frame inside a closure.

0 commit comments

Comments
 (0)