Update documentation

Compile Section Closes mattn#175 Compile Section Closes mattn#201 Compile Section Closes mattn#206 Compile Section Closes mattn#404 Compile Section Closes mattn#217 Compile Section Closes mattn#224 Compile Section Closes mattn#234 Compile Section Closes mattn#242 Feature table Closes mattn#255 Description Section Closes mattn#232 Golang:1.6 not supported Closes mattn#272 Golang:1.5 not supported + compilation section Closes mattn#283 usleep Implemented Closes mattn#285 FAQ Section Closes mattn#289 Compile Section closes mattn#295 FAQ Section Closes mattn#305 PR339 Closes mattn#318 mattn#321 Compilation Section Closes mattn#341 PR407 Closes mattn#364 Feature `sqlite_vtable` Closes mattn#393 Compile Section Closes mattn#416 sqlite_trace feature Closes mattn#433 Compilation Section Closes mattn#435 Compilation Section Closes mattn#443 Golang:1.6 Not Supported Closes mattn#445 Compilation Section Closes mattn#451 Compilation Section Closes mattn#467 Compilation Section Closes mattn#491 Compilation Section Closes mattn#495 Compilation Section Closes mattn#505 Compilation Section Closes mattn#557 Compilation Section Closes mattn#560
gjrtimmer · May 26, 2018 · 4a90a03 · 4a90a03
1 parent 3526997
commit 4a90a03
Showing 1 changed file with 181 additions and 15 deletions.
diff --git a/README.md b/README.md
@@ -10,11 +10,29 @@ go-sqlite3
 
 sqlite3 driver conforming to the built-in database/sql interface
 
+Supported Golang version:
+- 1.8.x
+- 1.9.x
+- 1.10.x
+
 ### Overview
 
 - [Installation](#installation)
 - [API Reference](#api-reference)
 - [Features](#features)
+- [Compilation](#compilation)
+  - [Android](#android)
+  - [ARM](#arm)
+  - [Cross Compile](#cross-compile)
+  - [Docker](#docker)
+    - [Alpine](#alpine)
+  - [Google Cloud Platform](#google-cloud-platform)
+  - [Linux](#linux)
+    - [Fedora](#fedora)
+    - [Ubuntu](#ubuntu)
+  - [Mac OSX](#mac-osx)
+  - [Windows](#windows)
+  - [Errors](#errors)
 - [FAQ](#faq)
 - [License](#license)
 
@@ -28,6 +46,8 @@ _go-sqlite3_ is *cgo* package.
 If you want to build your app using go-sqlite3, you need gcc.
 However, after you have built and installed _go-sqlite3_ with `go install github.com/mattn/go-sqlite3` (which requires gcc), you can build your app without relying on gcc in future.
 
+***Important: because this is a `CGO` enabled package you are required to set the environment variable `CGO_ENABLED=1` and have a `gcc` compile present within your path.***
+
 # API Reference
 
 API documentation can be found here: http://godoc.org/github.com/mattn/go-sqlite3
@@ -76,23 +96,168 @@ go build --tags "icu json1 fts5 secure_delete"
 | Secure Delete | sqlite_secure_delete | This compile-time option changes the default setting of the secure_delete pragma.<br><br>When this option is not used, secure_delete defaults to off. When this option is present, secure_delete defaults to on.<br><br>The secure_delete setting causes deleted content to be overwritten with zeros. There is a small performance penalty since additional I/O must occur.<br><br>On the other hand, secure_delete can prevent fragments of sensitive information from lingering in unused parts of the database file after it has been deleted. See the documentation on the secure_delete pragma for additional information |
 | Tracing / Debug | sqlite_trace | Activate trace functions |
 
-# FAQ
+# Compilation
+
+This package requires `CGO_ENABLED=1` ennvironment variable if not set by default, and the presence of the `gcc` compiler.
+
+If you need to add additional CFLAGS or LDFLAGS to the build command, and do not want to modify this package. Then this can be achieved by  using the `CGO_CFLAGS` and `CGO_LDFLAGS` environment variables.
+
+## Android
+
+This package can be compiled for android.
+Compile with:
+
+```bash
+go build --tags "android"
+```
+
+For more information see [#201](https://github.com/mattn/go-sqlite3/issues/201)
+
+# ARM
+
+To compile for `ARM` use the following environment.
+
+```bash
+env CC=arm-linux-gnueabihf-gcc CXX=arm-linux-gnueabihf-g++ \
+    CGO_ENABLED=1 GOOS=linux GOARCH=arm GOARM=7 \
+    go build -v 
+```
+
+Additional information:
+- [#242](https://github.com/mattn/go-sqlite3/issues/242)
+- [#504](https://github.com/mattn/go-sqlite3/issues/504)
+
+# Cross Compile
+
+This library can be cross-compiled.
+
+In some cases you are required to the `CC` environment variable with the cross compiler.
+
+Additional information:
+- [#491](https://github.com/mattn/go-sqlite3/issues/491)
+- [#560](https://github.com/mattn/go-sqlite3/issues/560)
+
+## Docker
+
+### Alpine
+
+When building in an `alpine` container run the following command before building.
+
+```
+apk add --update gcc musl-dev
+```
+
+# Google Cloud Platform
+
+Building on GCP is not possible because `Google Cloud Platform does not allow `gcc` to be executed.
+
+Please work only with compiled final binaries.
+
+## Linux
+
+To compile this package on Linux you must install the development tools for your linux distribution.
 
-- Want to build go-sqlite3 with libsqlite3 on my linux.
+To compile under linux use the build tag `linux`.
 
-    Use `go build --tags "libsqlite3 linux"`
+```bash
+go build --tags "linux"
+```
+
+If you wish to link directly to libsqlite3 then you can use the `libsqlite3` build tag.
+
+```
+go build --tags "libsqlite3 linux"
+```
 
-- Want to build go-sqlite3 with libsqlite3 on OS X.
+### Fedora
 
-    Install sqlite3 from homebrew: `brew install sqlite3`
+```bash
+sudo yum groupinstall "Development Tools" "Development Libraries"
+```
+
+### Ubuntu
+
+```bash
+sudo apt-get install build-essential
+```
+
+## Mac OSX
+
+OSX should have all the tools present to compile this package, if not install XCode this will add all the developers tools.
+
+Required dependency
+
+```bash
+brew install sqlite3
+```
 
-    Use `go build --tags "libsqlite3 darwin"`
+For OSX there is an additional package install which is required if you whish to build the `icu` extension.
+
+This additional package can be installed with `homebrew`.
+
+```bash
+brew upgrade icu4c
+```
+
+To compile for Mac OSX.
+
+```bash
+go build --tags "darwin"
+```
+
+If you wish to link directly to libsqlite3 then you can use the `libsqlite3` build tag.
+
+```
+go build --tags "libsqlite3 darwin"
+```
+
+Additional information:
+- [#206](https://github.com/mattn/go-sqlite3/issues/206)
+- [#404](https://github.com/mattn/go-sqlite3/issues/404)
+
+## Windows
+
+To compile this package on Windows OS you must have the `gcc` compiler installed.
+
+1) Install a Windows `gcc` toolchain.
+2) Add the `bin` folders to the Windows path if the installer did not do this by default.
+3) Open a terminal for the TDM-GCC toolchain, can be found in the Windows Start menu.
+4) Navigate to your project folder and run the `go build ...` command for this package.
+
+For example the TDM-GCC Toolchain can be found [here](ttps://sourceforge.net/projects/tdm-gcc/).
+
+## Errors
+
+- Compile error: `can not be used when making a shared object; recompile with -fPIC`
+
+    When receiving a compile time error referencing recompile with `-FPIC` then you
+    are probably using a hardend system.
+
+    You can copile the library on a hardend system with the following command.
+
+    ```bash
+    go build -ldflags '-extldflags=-fno-PIC'
+    ```
+
+    More details see [#120](https://github.com/mattn/go-sqlite3/issues/120)
 
 - Can't build go-sqlite3 on windows 64bit.
 
     > Probably, you are using go 1.0, go1.0 has a problem when it comes to compiling/linking on windows 64bit.
     > See: [#27](https://github.com/mattn/go-sqlite3/issues/27)
 
+- `go get github.com/mattn/go-sqlite3` throws compilation error.
+
+    `gcc` throws: `internal compiler error`
+
+    Remove the download repository from your disk and try re-install with:
+
+    ```bash
+    go install github.com/mattn/go-sqlite3
+    ```
+
+# FAQ
+
 - Getting insert error while query is opened.
 
     > You can pass some arguments into the connection string, for example, a URI.
@@ -120,19 +285,20 @@ go build --tags "icu json1 fts5 secure_delete"
     connection to this string will point to the same in-memory database. See
     [#204](https://github.com/mattn/go-sqlite3/issues/204) for more info.
 
-- Compile error: `can not be used when making a shared object; recompile with -fPIC`
+- Reading from database with large amount of goroutines fails on OSX.
 
-    When receiving a compile time error referencing recompile with `-FPIC` then you
-    are probably using a hardend system.
+    OS X limits OS-wide to not have more than 1000 files open simultaneously by default.
 
-    You can copile the library on a hardend system with the following command.
+    For more information see [#289](https://github.com/mattn/go-sqlite3/issues/289)
 
-    ```bash
-    go build -ldflags '-extldflags=-fno-PIC'
-    ```
+- Trying to execure a `.` (dot) command throws an error.
 
-    More details see [#120](https://github.com/mattn/go-sqlite3/issues/120)
-
+    Error: `Error: near ".": syntax error`
+    Dot command are part of SQLite3 CLI not of this library.
+
+    You need to implement the feature or call the sqlite3 cli.
+
+    More infomation see [#305](https://github.com/mattn/go-sqlite3/issues/305)
 
 # License