From 6d9f40bce71da1409f11c68a9084a6fb1092bba4 Mon Sep 17 00:00:00 2001 From: Dmitri Shuralyov Date: Fri, 16 Mar 2018 15:03:44 -0400 Subject: [PATCH 1/2] Document supported GOOS values. Add instructions for what people should do when building with GopherJS on unsupported platforms. Code generation works completely fine, but syscalls (e.g., for gopherjs run) will only work on supported platforms. Previously, this information was only in issues, people's heads, commit messages, etc. It should be documented in README to provide clarity. Rename "OS X" to "macOS", the current name of that operating system. Rearrange sections to place more relevant information first. Mention Linux before macOS consistently. Linux is placed first because it's open source and more freely available than the proprietary macOS, so it's easier to recommend it as an alternative. Resolves #770. Updates #776. Updates #688. --- README.md | 4 +++- doc/syscalls.md | 12 ++++++------ 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index b10362e83..d1b969e83 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,8 @@ go get -u github.com/gopherjs/gopherjs 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. +`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]`. + *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.* #### gopherjs run, gopherjs test @@ -31,7 +33,7 @@ If you want to use `gopherjs run` or `gopherjs test` to run the generated code l npm install --global source-map-support ``` -For system calls (file system access, etc.), see [this page](https://github.com/gopherjs/gopherjs/blob/master/doc/syscalls.md). +System calls (file system access, etc.) will work only supported `GOOS` platforms (see above). See [doc/syscalls.md](https://github.com/gopherjs/gopherjs/blob/master/doc/syscalls.md) for instructions. #### gopherjs serve diff --git a/doc/syscalls.md b/doc/syscalls.md index 2ac55d314..c0c051dda 100644 --- a/doc/syscalls.md +++ b/doc/syscalls.md @@ -11,13 +11,9 @@ If system calls are not available in your environment (see below), then a specia The JavaScript environment of a web browser is completely isolated from your operating system to protect your machine. You don't want any web page to read or write files on your disk without your consent. That is why system calls are not and will never be available when running your code in a web browser. -### Node.js on Windows - -When running your code with Node.js on Windows, it is theoretically possible to use system calls. To do so, you would need a special Node.js module that provides direct access to system calls. However, since the interface is quite different from the one used on OS X and Linux, the system calls module included in GopherJS currently does not support Windows. Sorry. Get in contact if you feel like you want to change this situation. - -### Node.js on OS X and Linux +### Node.js on Linux and macOS -GopherJS has support for system calls on OS X and Linux. Before running your code with Node.js, you need to install the system calls module. The module is compatible with Node.js version 0.12 and above. If you want to use an older version you can opt to not install the module, but then system calls are not available. +GopherJS has support for system calls on Linux and macOS. Before running your code with Node.js, you need to install the system calls module. The module is compatible with Node.js version 0.12 and above. If you want to use an older version you can opt to not install the module, but then system calls are not available. Compile and install the module with: ``` @@ -28,6 +24,10 @@ mkdir -p ~/.node_libraries/ cp build/Release/syscall.node ~/.node_libraries/syscall.node ``` +### Node.js on Windows + +When running your code with Node.js on Windows, it is theoretically possible to use system calls. To do so, you would need a special Node.js module that provides direct access to system calls. However, since the interface is quite different from the one used on Linux and macOS, the system calls module included in GopherJS currently does not support Windows. Sorry. Get in contact if you feel like you want to change this situation. + ### Caveats Note that even with syscalls enabled in Node.js, some programs may not behave as expected due to the fact that the current implementation blocks other goroutines during a syscall, which can lead to a deadlock in some situations. This is not considered a bug, as it is considered sufficient for most test cases (which is all Node.js should be used for). Get in contact if you feel like you want to change this situation. From 114a4ac538f45ad598b948d33b4f7e4089203110 Mon Sep 17 00:00:00 2001 From: Dmitri Shuralyov Date: Fri, 16 Mar 2018 23:58:44 -0400 Subject: [PATCH 2/2] Rewrite paragraph to improve clarity and accuracy. Previous sentence was missing a word, and didn't sound great. --- README.md | 2 +- doc/syscalls.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d1b969e83..8c5e09011 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ If you want to use `gopherjs run` or `gopherjs test` to run the generated code l npm install --global source-map-support ``` -System calls (file system access, etc.) will work only supported `GOOS` platforms (see above). See [doc/syscalls.md](https://github.com/gopherjs/gopherjs/blob/master/doc/syscalls.md) for instructions. +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. #### gopherjs serve diff --git a/doc/syscalls.md b/doc/syscalls.md index c0c051dda..abefd9edb 100644 --- a/doc/syscalls.md +++ b/doc/syscalls.md @@ -16,6 +16,7 @@ The JavaScript environment of a web browser is completely isolated from your ope GopherJS has support for system calls on Linux and macOS. Before running your code with Node.js, you need to install the system calls module. The module is compatible with Node.js version 0.12 and above. If you want to use an older version you can opt to not install the module, but then system calls are not available. Compile and install the module with: + ``` cd $GOPATH/src/github.com/gopherjs/gopherjs/node-syscall/ npm install --global node-gyp