github.com/goplusjs/gopherjs@v1.2.6-0.20211206034512-f187917453b8/README.md (about)

     1  GopherJS - A compiler from Go to JavaScript
     2  -------------------------------------------
     3  [![Go1.12](https://github.com/goplusjs/gopherjs/workflows/Go1.12/badge.svg)](https://github.com/goplusjs/gopherjs/actions?query=workflow%3AGo1.12)
     4  [![Go1.13](https://github.com/goplusjs/gopherjs/workflows/Go1.13/badge.svg)](https://github.com/goplusjs/gopherjs/actions?query=workflow%3AGo1.13)
     5  [![Go1.14](https://github.com/goplusjs/gopherjs/workflows/Go1.14/badge.svg)](https://github.com/goplusjs/gopherjs/actions?query=workflow%3AGo1.14)
     6  [![Go1.15](https://github.com/goplusjs/gopherjs/workflows/Go1.15/badge.svg)](https://github.com/goplusjs/gopherjs/actions?query=workflow%3AGo1.15)
     7  [![Go1.16](https://github.com/goplusjs/gopherjs/workflows/Go1.16/badge.svg)](https://github.com/goplusjs/gopherjs/actions?query=workflow%3AGo1.16)
     8  
     9  ### GopherJS
    10  This version of GopherJS is a fork of the <https://github.com/gopherjs/gopherjs>
    11  
    12  Supported Go version
    13  Go1.12 Go1.13 Go1.14 Go1.15 Go1.16
    14  
    15  ```
    16  go get -u github.com/goplusjs/gopherjs
    17  ```
    18  
    19  
    20  ### syscall/js
    21  ```
    22  package main
    23  
    24  import (
    25  	"syscall/js"
    26  )
    27  
    28  func main() {
    29  	js.Global().Get("document").Call("write", "Hello world!")
    30  }
    31  ```
    32  
    33  ```
    34  $ gopherjs serve
    35  ```
    36  
    37  
    38  ***
    39  
    40  
    41  [![GoDoc](https://godoc.org/github.com/gopherjs/gopherjs/js?status.svg)](https://godoc.org/github.com/gopherjs/gopherjs/js)
    42  [![Sourcegraph](https://sourcegraph.com/github.com/gopherjs/gopherjs/-/badge.svg)](https://sourcegraph.com/github.com/gopherjs/gopherjs?badge)
    43  
    44  GopherJS compiles Go code ([golang.org](https://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.
    45  
    46  ### Playground
    47  Give GopherJS a try on the [GopherJS Playground](http://gopherjs.github.io/playground/).
    48  
    49  ### What is supported?
    50  Nearly everything, including Goroutines ([compatibility table](https://github.com/gopherjs/gopherjs/blob/master/doc/packages.md)). Performance is quite good in most cases, see [HTML5 game engine benchmark](https://ajhager.github.io/engi/demos/botmark.html). Cgo is not supported.
    51  
    52  ### Installation and Usage
    53  Get or update GopherJS and dependencies with:
    54  
    55  ```
    56  go get -u github.com/gopherjs/gopherjs
    57  ```
    58  
    59  Now you can use `gopherjs build [package]`, `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.
    60  
    61  `gopherjs` uses your platform's default `GOOS` value when generating code. Supported `GOOS` values are: `linux`, `darwin`. If you're on a different platform (e.g., Windows or FreeBSD), you'll need to set the `GOOS` environment variable to a supported value. For example, `GOOS=linux gopherjs build [package]`.
    62  
    63  *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.*
    64  
    65  #### gopherjs run, gopherjs test
    66  
    67  If you want to use `gopherjs run` or `gopherjs test` to run the generated code locally, install Node.js 10.0.0 (or newer), and the `source-map-support` module:
    68  
    69  ```
    70  npm install --global source-map-support
    71  ```
    72  
    73  On supported `GOOS` platforms, it's possible to make system calls (file system access, etc.) available. See [doc/syscalls.md](https://github.com/gopherjs/gopherjs/blob/master/doc/syscalls.md) for instructions on how to do so.
    74  
    75  #### gopherjs serve
    76  
    77  `gopherjs serve` is a useful command you can use during development. It will start an HTTP server serving on ":8080" by default, then dynamically compile your Go packages with GopherJS and serve them.
    78  
    79  For example, navigating to `http://localhost:8080/example.com/user/project/` should compile and run the Go package `example.com/user/project`. The generated JavaScript output will be served at `http://localhost:8080/example.com/user/project/project.js` (the .js file name will be equal to the base directory name). If the directory contains `index.html` it will be served, otherwise a minimal `index.html` that includes `<script src="project.js"></script>` will be provided, causing the JavaScript to be executed. All other static files will be served too.
    80  
    81  Refreshing in the browser will rebuild the served files if needed. Compilation errors will be displayed in terminal, and in browser console. Additionally, it will serve $GOROOT and $GOPATH for sourcemaps.
    82  
    83  If you include an argument, it will be the root from which everything is served. For example, if you run `gopherjs serve github.com/user/project` then the generated JavaScript for the package github.com/user/project/mypkg will be served at http://localhost:8080/mypkg/mypkg.js.
    84  
    85  ### Performance Tips
    86  
    87  - Use the `-m` command line flag to generate minified code.
    88  - Apply gzip compression (https://en.wikipedia.org/wiki/HTTP_compression).
    89  - Use `int` instead of `(u)int8/16/32/64`.
    90  - Use `float64` instead of `float32`.
    91  
    92  ### Community
    93  - [#gopherjs Channel on Gophers Slack](https://gophers.slack.com/messages/gopherjs/) (invites to Gophers Slack are available [here](http://blog.gopheracademy.com/gophers-slack-community/#how-can-i-be-invited-to-join:2facdc921b2310f18cb851c36fa92369))
    94  - [Bindings to JavaScript APIs and libraries](https://github.com/gopherjs/gopherjs/wiki/bindings)
    95  - [GopherJS Blog](https://medium.com/gopherjs)
    96  - [GopherJS on Twitter](https://twitter.com/GopherJS)
    97  
    98  ### Getting started
    99  
   100  #### Interacting with the DOM
   101  The package `github.com/gopherjs/gopherjs/js` (see [documentation](https://godoc.org/github.com/gopherjs/gopherjs/js)) provides functions for interacting with native JavaScript APIs. For example the line
   102  
   103  ```js
   104  document.write("Hello world!");
   105  ```
   106  
   107  would look like this in Go:
   108  
   109  ```go
   110  js.Global.Get("document").Call("write", "Hello world!")
   111  ```
   112  
   113  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/wvell/go-angularjs). Those are some of the [bindings to JavaScript APIs and libraries](https://github.com/gopherjs/gopherjs/wiki/bindings) by community members.
   114  
   115  #### Providing library functions for use in other JavaScript code
   116  Set a global variable to a map that contains the functions:
   117  
   118  ```go
   119  package main
   120  
   121  import "github.com/gopherjs/gopherjs/js"
   122  
   123  func main() {
   124  	js.Global.Set("pet", map[string]interface{}{
   125  		"New": New,
   126  	})
   127  }
   128  
   129  type Pet struct {
   130  	name string
   131  }
   132  
   133  func New(name string) *js.Object {
   134  	return js.MakeWrapper(&Pet{name})
   135  }
   136  
   137  func (p *Pet) Name() string {
   138  	return p.name
   139  }
   140  
   141  func (p *Pet) SetName(name string) {
   142  	p.name = name
   143  }
   144  ```
   145  
   146  For more details see [Jason Stone's blog post](http://legacytotheedge.blogspot.de/2014/03/gopherjs-go-to-javascript-transpiler.html) about GopherJS.
   147  
   148  ### Architecture
   149  
   150  #### General
   151  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`.
   152  
   153  #### Application Lifecycle
   154  
   155  The `main` function is executed as usual after all `init` functions have run. JavaScript callbacks can also invoke Go functions, even after the `main` function has exited. Therefore the end of the `main` function should not be regarded as the end of the application and does not end the execution of other goroutines.
   156  
   157  In the browser, calling `os.Exit` (e.g. indirectly by `log.Fatal`) also does not terminate the execution of the program. For convenience, it calls `runtime.Goexit` to immediately terminate the calling goroutine.
   158  
   159  #### Goroutines
   160  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:
   161  
   162  ```go
   163  js.Global.Get("myButton").Call("addEventListener", "click", func() {
   164    go func() {
   165      [...]
   166      someBlockingFunction()
   167      [...]
   168    }()
   169  })
   170  ```
   171  
   172  How it works:
   173  
   174  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.
   175  
   176  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.
   177  
   178  ### GopherJS Development
   179  If you're looking to make changes to the GopherJS compiler, see [Developer Guidelines](https://github.com/gopherjs/gopherjs/wiki/Developer-Guidelines) for additional developer information.