From 56869e2328ca8a4fa463defbe4ca8decb8a860db Mon Sep 17 00:00:00 2001 From: Mike Dalessio Date: Wed, 24 May 2023 11:29:30 -0400 Subject: [PATCH 1/3] doc: promote the FAQ to the root directory drop the old faq.rb, faq.rb, and faq.rake files --- faq/faq.md => FAQ.md | 0 faq/faq.rb | 145 --------------- faq/faq.yml | 426 ------------------------------------------- rakelib/faq.rake | 9 - sqlite3.gemspec | 4 +- 5 files changed, 1 insertion(+), 583 deletions(-) rename faq/faq.md => FAQ.md (100%) delete mode 100644 faq/faq.rb delete mode 100644 faq/faq.yml delete mode 100644 rakelib/faq.rake diff --git a/faq/faq.md b/FAQ.md similarity index 100% rename from faq/faq.md rename to FAQ.md diff --git a/faq/faq.rb b/faq/faq.rb deleted file mode 100644 index 61d7d01c..00000000 --- a/faq/faq.rb +++ /dev/null @@ -1,145 +0,0 @@ -require 'yaml' -require 'redcloth' - -def process_faq_list( faqs ) - puts "" -end - -def process_faq_list_item( faq ) - question = faq.keys.first - answer = faq.values.first - - print "
  • " - - question_text = RedCloth.new(question).to_html.gsub( %r{},"" ) - if answer.is_a?( Array ) - puts question_text - process_faq_list answer - else - print "#{question_text}" - end - - puts "
    • " -end - -def process_faq_descriptions( faqs, path=nil ) - faqs.each do |faq| - process_faq_description faq, path - end -end - -def process_faq_description( faq, path ) - question = faq.keys.first - path = ( path ? path + " " : "" ) + question - answer = faq.values.first - - if answer.is_a?( Array ) - process_faq_descriptions( answer, path ) - else - title = RedCloth.new( path ).to_html.gsub( %r{}, "" ) - answer = RedCloth.new( answer || "" ) - - puts "" - puts "
    #{title}
    " - puts "
    #{add_api_links(answer.to_html)}
    " - end -end - -API_OBJECTS = [ "Database", "Statement", "ResultSet", - "ParsedStatement", "Pragmas", "Translator" ].inject( "(" ) { |acc,name| - acc << "|" if acc.length > 1 - acc << name - acc - } + ")" - -def add_api_links( text ) - text.gsub( /#{API_OBJECTS}(#(\w+))?/ ) do - disp_obj = obj = $1 - - case obj - when "Pragmas"; disp_obj = "Database" - end - - method = $3 - s = "#{disp_obj}" - s << "##{method}" if method - s << "" - s - end -end - -faqs = YAML.load( File.read( "faq.yml" ) ) - -puts <<-EOF - - - SQLite3/Ruby FAQ - - - -

    SQLite/Ruby FAQ

    -
    -EOF - -process_faq_list( faqs ) -puts "
    " -process_faq_descriptions( faqs ) - -puts "" diff --git a/faq/faq.yml b/faq/faq.yml deleted file mode 100644 index 2360ae73..00000000 --- a/faq/faq.yml +++ /dev/null @@ -1,426 +0,0 @@ ---- -- "How do I do a database query?": - - "I just want an array of the rows...": >- - - Use the Database#execute method. If you don't give it a block, it will - return an array of all the rows: - - - 
    -        require 'sqlite3'
-
-        db = SQLite3::Database.new( "test.db" )
-        rows = db.execute( "select * from test" )
-
    - - - "I'd like to use a block to iterate through the rows...": >- - - Use the Database#execute method. If you give it a block, each row of the - result will be yielded to the block: - - - 
    -        require 'sqlite3'
-
-        db = SQLite3::Database.new( "test.db" )
-        db.execute( "select * from test" ) do |row|
-          ...
-        end
-
    - - - "I need to get the column names as well as the rows...": >- - - Use the Database#execute2 method. This works just like Database#execute; - if you don't give it a block, it returns an array of rows; otherwise, it - will yield each row to the block. _However_, the first row returned is - always an array of the column names from the query: - - - 
    -        require 'sqlite3'
-
-        db = SQLite3::Database.new( "test.db" )
-        columns, *rows = db.execute2( "select * from test" )
-
-        # or use a block:
-
-        columns = nil
-        db.execute2( "select * from test" ) do |row|
-          if columns.nil?
-            columns = row
-          else
-            # process row
-          end
-        end
-
    - - - "I just want the first row of the result set...": >- - - Easy. Just call Database#get_first_row: - - - 
    -        row = db.get_first_row( "select * from table" )
-
    - - - This also supports bind variables, just like Database#execute - and friends. - - - "I just want the first value of the first row of the result set...": >- - - Also easy. Just call Database#get_first_value: - - - 
    -        count = db.get_first_value( "select count(*) from table" )
-
    - - - This also supports bind variables, just like Database#execute - and friends. - -- "How do I prepare a statement for repeated execution?": >- - If the same statement is going to be executed repeatedly, you can speed - things up a bit by _preparing_ the statement. You do this via the - Database#prepare method. It returns a Statement object, and you can - then invoke #execute on that to get the ResultSet: - - - 
    -      stmt = db.prepare( "select * from person" )
-
-      1000.times do
-        stmt.execute do |result|
-          ...
-        end
-      end
-
-      stmt.close
-
-      # or, use a block
-
-      db.prepare( "select * from person" ) do |stmt|
-        1000.times do
-          stmt.execute do |result|
-            ...
-          end
-        end
-      end
-
    - - - This is made more useful by the ability to bind variables to placeholders - via the Statement#bind_param and Statement#bind_params methods. (See the - next FAQ for details.) - -- "How do I use placeholders in an SQL statement?": >- - Placeholders in an SQL statement take any of the following formats: - - - * @?@ - - * @?_nnn_@ - - * @:_word_@ - - - Where _n_ is an integer, and _word_ is an alpha-numeric identifier (or - number). When the placeholder is associated with a number, that number - identifies the index of the bind variable to replace it with. When it - is an identifier, it identifies the name of the corresponding bind - variable. (In the instance of the first format--a single question - mark--the placeholder is assigned a number one greater than the last - index used, or 1 if it is the first.) - - - For example, here is a query using these placeholder formats: - - - 
    -      select *
-        from table
-       where ( c = ?2 or c = ? )
-         and d = :name
-         and e = :1
-
    - - - This defines 5 different placeholders: 1, 2, 3, and "name". - - - You replace these placeholders by _binding_ them to values. This can be - accomplished in a variety of ways. - - - The Database#execute, and Database#execute2 methods all accept additional - arguments following the SQL statement. These arguments are assumed to be - bind parameters, and they are bound (positionally) to their corresponding - placeholders: - - - 
    -      db.execute( "select * from table where a = ? and b = ?",
-                  "hello",
-                  "world" )
-
    - - - The above would replace the first question mark with 'hello' and the - second with 'world'. If the placeholders have an explicit index given, they - will be replaced with the bind parameter at that index (1-based). - - - If a Hash is given as a bind parameter, then its key/value pairs are bound - to the placeholders. This is how you bind by name: - - - 
    -      db.execute( "select * from table where a = :name and b = :value",
-                  "name" => "bob",
-                  "value" => "priceless" )
-
    - - - You can also bind explicitly using the Statement object itself. Just pass - additional parameters to the Statement#execute statement: - - - 
    -      db.prepare( "select * from table where a = :name and b = ?" ) do |stmt|
-        stmt.execute "value", "name" => "bob"
-      end
-
    - - - Or do a Database#prepare to get the Statement, and then use either - Statement#bind_param or Statement#bind_params: - - - 
    -      stmt = db.prepare( "select * from table where a = :name and b = ?" )
-
-      stmt.bind_param( "name", "bob" )
-      stmt.bind_param( 1, "value" )
-
-      # or
-
-      stmt.bind_params( "value", "name" => "bob" )
-
    - -- "How do I discover metadata about a query?": >- - - If you ever want to know the names or types of the columns in a result - set, you can do it in several ways. - - - The first way is to ask the row object itself. Each row will have a - property "fields" that returns an array of the column names. The row - will also have a property "types" that returns an array of the column - types: - - - 
    -      rows = db.execute( "select * from table" )
-      p rows[0].fields
-      p rows[0].types
-
    - - - Obviously, this approach requires you to execute a statement that actually - returns data. If you don't know if the statement will return any rows, but - you still need the metadata, you can use Database#query and ask the - ResultSet object itself: - - - 
    -      db.query( "select * from table" ) do |result|
-        p result.columns
-        p result.types
-        ...
-      end
-
    - - - Lastly, you can use Database#prepare and ask the Statement object what - the metadata are: - - - 
    -      stmt = db.prepare( "select * from table" )
-      p stmt.columns
-      p stmt.types
-
    - -- "I'd like the rows to be indexible by column name.": >- - By default, each row from a query is returned as an Array of values. This - means that you can only obtain values by their index. Sometimes, however, - you would like to obtain values by their column name. - - - The first way to do this is to set the Database property "results_as_hash" - to true. If you do this, then all rows will be returned as Hash objects, - with the column names as the keys. (In this case, the "fields" property - is unavailable on the row, although the "types" property remains.) - - - 
    -      db.results_as_hash = true
-      db.execute( "select * from table" ) do |row|
-        p row['column1']
-        p row['column2']
-      end
-
    - - - The other way is to use Ara Howard's - "ArrayFields":http://rubyforge.org/projects/arrayfields - module. Just require "arrayfields", and all of your rows will be indexable - by column name, even though they are still arrays! - - - 
    -      require 'arrayfields'
-
-      ...
-      db.execute( "select * from table" ) do |row|
-        p row[0] == row['column1']
-        p row[1] == row['column2']
-      end
-
    - -- "I'd like the values from a query to be the correct types, instead of String.": >- - You can turn on "type translation" by setting Database#type_translation to - true: - - - 
    -      db.type_translation = true
-      db.execute( "select * from table" ) do |row|
-        p row
-      end
-
    - - - By doing this, each return value for each row will be translated to its - correct type, based on its declared column type. - - - You can even declare your own translation routines, if (for example) you are - using an SQL type that is not handled by default: - - - 
    -      # assume "objects" table has the following schema:
-      #   create table objects (
-      #     name varchar2(20),
-      #     thing object
-      #   )
-
-      db.type_translation = true
-      db.translator.add_translator( "object" ) do |type, value|
-        db.decode( value )
-      end
-
-      h = { :one=>:two, "three"=>"four", 5=>6 }
-      dump = db.encode( h )
-
-      db.execute( "insert into objects values ( ?, ? )", "bob", dump )
-
-      obj = db.get_first_value( "select thing from objects where name='bob'" )
-      p obj == h
-
    - -- "How do I insert binary data into the database?": >- - Use blobs. Blobs are new features of SQLite3. You have to use bind - variables to make it work: - - - 
    -      db.execute( "insert into foo ( ?, ? )",
-        SQLite3::Blob.new( "\0\1\2\3\4\5" ),
-        SQLite3::Blob.new( "a\0b\0c\0d ) )
-
    - - - The blob values must be indicated explicitly by binding each parameter to - a value of type SQLite3::Blob. - -- "How do I do a DDL (insert, update, delete) statement?": >- - You can actually do inserts, updates, and deletes in exactly the same way - as selects, but in general the Database#execute method will be most - convenient: - - - 
    -      db.execute( "insert into table values ( ?, ? )", *bind_vars )
-
    - -- "How do I execute multiple statements in a single string?": >- - The standard query methods (Database#execute, Database#execute2, - Database#query, and Statement#execute) will only execute the first - statement in the string that is given to them. Thus, if you have a - string with multiple SQL statements, each separated by a string, - you can't use those methods to execute them all at once. - - - Instead, use Database#execute_batch: - - - 
    -      sql = <
-
-
-    Unlike the other query methods, Database#execute_batch accepts no
-    block. It will also only ever return +nil+. Thus, it is really only
-    suitable for batch processing of DDL statements.
-
-- "How do I begin/end a transaction?":
-    Use Database#transaction to start a transaction. If you give it a block,
-    the block will be automatically committed at the end of the block,
-    unless an exception was raised, in which case the transaction will be
-    rolled back. (Never explicitly call Database#commit or Database#rollback
-    inside of a transaction block--you'll get errors when the block
-    terminates!)
-
-
-    
    -      database.transaction do |db|
-        db.execute( "insert into table values ( 'a', 'b', 'c' )" )
-        ...
-      end
-    
    
-
-
-    Alternatively, if you don't give a block to Database#transaction, the
-    transaction remains open until you explicitly call Database#commit or
-    Database#rollback.
-
-
-    
    -      db.transaction
-      db.execute( "insert into table values ( 'a', 'b', 'c' )" )
-      db.commit
-    
    
-
-
-    Note that SQLite does not allow nested transactions, so you'll get errors
-    if you try to open a new transaction while one is already active. Use
-    Database#transaction_active? to determine whether a transaction is
-    active or not.
-
-#- "How do I discover metadata about a table/index?":
-#
-#- "How do I do tweak database settings?":
diff --git a/rakelib/faq.rake b/rakelib/faq.rake
deleted file mode 100644
index 9f8f652d..00000000
--- a/rakelib/faq.rake
+++ /dev/null
@@ -1,9 +0,0 @@
-# Generate FAQ
-desc "Generate the FAQ document"
-task :faq => ['faq/faq.html']
-
-file 'faq/faq.html' => ['faq/faq.rb', 'faq/faq.yml'] do
-  cd 'faq' do
-    ruby "faq.rb > faq.html"
-  end
-end
diff --git a/sqlite3.gemspec b/sqlite3.gemspec
index 5c40d946..85c46e46 100644
--- a/sqlite3.gemspec
+++ b/sqlite3.gemspec
@@ -40,6 +40,7 @@ Gem::Specification.new do |s|
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "ChangeLog.cvs",
+    "FAQ.md",
     "Gemfile",
     "LICENSE",
     "LICENSE-DEPENDENCIES",
@@ -58,9 +59,6 @@ Gem::Specification.new do |s|
     "ext/sqlite3/sqlite3_ruby.h",
     "ext/sqlite3/statement.c",
     "ext/sqlite3/statement.h",
-    "faq/faq.md",
-    "faq/faq.rb",
-    "faq/faq.yml",
     "lib/sqlite3.rb",
     "lib/sqlite3/constants.rb",
     "lib/sqlite3/database.rb",

From 2dc58b7dadd45752776f773ee6aff623d67d026b Mon Sep 17 00:00:00 2001
From: Mike Dalessio 
Date: Wed, 24 May 2023 11:31:03 -0400
Subject: [PATCH 2/3] doc: extract install docs to INSTALLATION.md

and tweak/trim the README a bit
---
 INSTALLATION.md | 220 ++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       | 169 +++++--------------------------------
 sqlite3.gemspec |   1 +
 3 files changed, 243 insertions(+), 147 deletions(-)
 create mode 100644 INSTALLATION.md

diff --git a/INSTALLATION.md b/INSTALLATION.md
new file mode 100644
index 00000000..36253654
--- /dev/null
+++ b/INSTALLATION.md
@@ -0,0 +1,220 @@
+
+# Installation and Using SQLite3 extensions
+
+This document will help you install the `sqlite3` ruby gem. It also contains instructions on loading database extensions and building against drop-in replacements for sqlite3.
+
+## Installation
+
+### Native Gems (recommended)
+
+In v1.5.0 and later, native (precompiled) gems are available for recent Ruby versions on these platforms:
+
+- `aarch64-linux` (requires: glibc >= 2.29)
+- `arm-linux` (requires: glibc >= 2.29)
+- `arm64-darwin`
+- `x64-mingw32` / `x64-mingw-ucrt`
+- `x86-linux` (requires: glibc >= 2.17)
+- `x86_64-darwin`
+- `x86_64-linux` (requires: glibc >= 2.17)
+
+If you are using one of these Ruby versions on one of these platforms, the native gem is the recommended way to install sqlite3-ruby.
+
+For example, on a linux system running Ruby 3.1:
+
+``` text
+$ ruby -v
+ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [x86_64-linux]
+
+$ time gem install sqlite3
+Fetching sqlite3-1.5.0-x86_64-linux.gem
+Successfully installed sqlite3-1.5.0-x86_64-linux
+1 gem installed
+
+real    0m4.274s
+user    0m0.734s
+sys     0m0.165s
+```
+
+#### Avoiding the precompiled native gem
+
+The maintainers strongly urge you to use a native gem if at all possible. It will be a better experience for you and allow us to focus our efforts on improving functionality rather than diagnosing installation issues.
+
+If you're on a platform that supports a native gem but you want to avoid using it in your project, do one of the following:
+
+- If you're not using Bundler, then run `gem install sqlite3 --platform=ruby`
+- If you are using Bundler
+  - version 2.3.18 or later, you can specify [`gem "sqlite3", force_ruby_platform: true`](https://bundler.io/v2.3/man/gemfile.5.html#FORCE_RUBY_PLATFORM)
+  - version 2.1 or later, then you'll need to run `bundle config set force_ruby_platform true`
+  - version 2.0 or earlier, then you'll need to run `bundle config force_ruby_platform true`
+
+
+### Compiling the source gem
+
+If you are on a platform or version of Ruby that is not covered by the Native Gems, then the vanilla "ruby platform" (non-native) gem will be installed by the `gem install` or `bundle` commands.
+
+
+#### Packaged libsqlite3
+
+By default, as of v1.5.0 of this library, the latest available version of libsqlite3 is packaged with the gem and will be compiled and used automatically. This takes a bit longer than the native gem, but will provide a modern, well-supported version of libsqlite3.
+
+For example, on a linux system running Ruby 2.5:
+
+``` text
+$ ruby -v
+ruby 2.5.9p229 (2021-04-05 revision 67939) [x86_64-linux]
+
+$ time gem install sqlite3
+Building native extensions. This could take a while...
+Successfully installed sqlite3-1.5.0
+1 gem installed
+
+real    0m20.620s
+user    0m23.361s
+sys     0m5.839s
+```
+
+
+#### System libsqlite3
+
+If you would prefer to build the sqlite3-ruby gem against your system libsqlite3, which requires that you install libsqlite3 and its development files yourself, you may do so by using the `--enable-system-libraries` flag at gem install time.
+
+PLEASE NOTE:
+
+- you must avoid installing a precompiled native gem (see [previous section](#avoiding-the-precompiled-native-gem))
+- only versions of libsqlite3 `>= 3.5.0` are supported,
+- and some library features may depend on how your libsqlite3 was compiled.
+
+For example, on a linux system running Ruby 2.5:
+
+``` text
+$ time gem install sqlite3 -- --enable-system-libraries
+Building native extensions with: '--enable-system-libraries'
+This could take a while...
+Successfully installed sqlite3-1.5.0
+1 gem installed
+
+real    0m4.234s
+user    0m3.809s
+sys     0m0.912s
+```
+
+If you're using bundler, you can opt into system libraries like this:
+
+``` sh
+bundle config build.sqlite3 --enable-system-libraries
+```
+
+If you have sqlite3 installed in a non-standard location, you may need to specify the location of the include and lib files by using `--with-sqlite-include` and `--with-sqlite-lib` options (or a `--with-sqlite-dir` option, see [MakeMakefile#dir_config](https://ruby-doc.org/stdlib-3.1.1/libdoc/mkmf/rdoc/MakeMakefile.html#method-i-dir_config)). If you have pkg-config installed and configured properly, this may not be necessary.
+
+``` sh
+gem install sqlite3 -- \
+  --enable-system-libraries \
+  --with-sqlite3-include=/opt/local/include \
+  --with-sqlite3-lib=/opt/local/lib
+```
+
+
+#### System libsqlcipher
+
+If you'd like to link against a system-installed libsqlcipher, you may do so by using the `--with-sqlcipher` flag:
+
+``` text
+$ time gem install sqlite3 -- --with-sqlcipher
+Building native extensions with: '--with-sqlcipher'
+This could take a while...
+Successfully installed sqlite3-1.5.0
+1 gem installed
+
+real    0m4.772s
+user    0m3.906s
+sys     0m0.896s
+```
+
+If you have sqlcipher installed in a non-standard location, you may need to specify the location of the include and lib files by using `--with-sqlite-include` and `--with-sqlite-lib` options (or a `--with-sqlite-dir` option, see [MakeMakefile#dir_config](https://ruby-doc.org/stdlib-3.1.1/libdoc/mkmf/rdoc/MakeMakefile.html#method-i-dir_config)). If you have pkg-config installed and configured properly, this may not be necessary.
+
+
+## Using SQLite3 extensions
+
+### How do I load a sqlite extension?
+
+Some add-ons are available to sqlite as "extensions". The instructions that upstream sqlite provides at https://www.sqlite.org/loadext.html are the canonical source of advice, but here's a brief example showing how you can do this with the `sqlite3` ruby gem.
+
+In this example, I'll be loading the ["spellfix" extension](https://www.sqlite.org/spellfix1.html):
+
+``` text
+# download spellfix.c from somewherehttp://www.sqlite.org/src/finfo?name=ext/misc/spellfix.c
+$ wget https://raw.githubusercontent.com/sqlite/sqlite/master/ext/misc/spellfix.c
+spellfix.c                     100%[=================================================>] 100.89K  --.-KB/s    in 0.09s
+
+# follow instructions at https://www.sqlite.org/loadext.html
+# (you will need sqlite3 development packages for this)
+$ gcc -g -fPIC -shared spellfix.c -o spellfix.o
+
+$ ls -lt
+total 192
+-rwxrwxr-x 1 flavorjones flavorjones  87984 2023-05-24 10:44 spellfix.o
+-rw-rw-r-- 1 flavorjones flavorjones 103310 2023-05-24 10:43 spellfix.c
+```
+
+Then, in your application, use that `spellfix.o` file like this:
+
+``` ruby
+require "sqlite3"
+
+db = SQLite3::Database.new(':memory:')
+db.enable_load_extension(true)
+db.load_extension("/path/to/sqlite/spellfix.o")
+db.execute("CREATE VIRTUAL TABLE demo USING spellfix1;")
+```
+
+### How do I use an alternative sqlite3 implementation?
+
+Some packages, like pSQLite Encryption Extension ("SEE"), are intended to be ABI-compatible drop-in replacements for the sqlite3 shared object.
+
+If you've installed your alternative as an autotools-style installation, the directory structure will look like this:
+
+```
+/opt/see
+├── bin
+│   └── sqlite3
+├── include
+│   ├── sqlite3.h
+│   └── sqlite3ext.h
+├── lib
+│   ├── libsqlite3.a
+│   ├── libsqlite3.la
+│   ├── libsqlite3.so -> libsqlite3.so.0.8.6
+│   ├── libsqlite3.so.0 -> libsqlite3.so.0.8.6
+│   ├── libsqlite3.so.0.8.6
+│   └── pkgconfig
+│       └── sqlite3.pc
+└── share
+    └── man
+        └── man1
+            └── sqlite3.1
+```
+
+You can build this gem against that library like this:
+
+```
+gem install sqlite3 --platform=ruby -- \
+  --enable-system-libraries \
+  --with-opt-dir=/opt/see
+```
+
+Explanation:
+
+- use `--platform=ruby` to avoid the precompiled native gems (see the README)
+- the `--` separates arguments passed to "gem install" from arguments passed to the C extension builder
+- use `--enable-system-libraries` to avoid the vendored sqlite3 source
+- use `--with-opt-dir=/path/to/installation` to point the build process at the desired header files and shared object files
+
+Alternatively, if you've simply downloaded an "amalgamation" and so your compiled library and header files are in arbitrary locations, try this more detailed command:
+
+```
+gem install sqlite3 --platform=ruby -- \
+  --enable-system-libraries \
+  --with-opt-include=/path/to/include \
+  --with-opt-lib=/path/to/lib
+```
+
diff --git a/README.md b/README.md
index 19df6755..7930dc4e 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,11 @@
 # Ruby Interface for SQLite3
 
+## Overview
+
+This library allows Ruby programs to use the SQLite3 database engine (http://www.sqlite.org).
+
+Note that this module is only compatible with SQLite 3.6.16 or newer.
+
 * Source code: https://github.com/sparklemotion/sqlite3-ruby
 * Mailing list: http://groups.google.com/group/sqlite3-ruby
 * Download: http://rubygems.org/gems/sqlite3
@@ -9,14 +15,18 @@
 [![Native packages](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/gem-install.yml/badge.svg)](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/gem-install.yml)
 
 
-## Description
+## Quick start
 
-This library allows Ruby programs to use the SQLite3 database engine (http://www.sqlite.org).
+For help understanding the SQLite3 Ruby API, please read the [FAQ](./FAQ.md) and the [full API documentation](https://rubydoc.info/gems/sqlite3).
 
-Note that this module is only compatible with SQLite 3.6.16 or newer.
+A few key classes whose APIs are often-used are:
+
+- SQLite3::Database ([rdoc](https://rubydoc.info/gems/sqlite3/SQLite3/Database))
+- SQLite3::Statement ([rdoc](https://rubydoc.info/gems/sqlite3/SQLite3/Statement))
+- SQLite3::ResultSet ([rdoc](https://rubydoc.info/gems/sqlite3/SQLite3/ResultSet))
 
+If you have any questions that you feel should be addressed in the FAQ, please send them to [the mailing list](http://groups.google.com/group/sqlite3-ruby) or open a [discussion thread](https://github.com/sparklemotion/sqlite3-ruby/discussions/categories/q-a).
 
-## Synopsis
 
 ``` ruby
 require "sqlite3"
@@ -67,157 +77,22 @@ end
 # => ["Jane", "me@janedoe.com", "A", "http://blog.janedoe.com"]
 ```
 
-## Installation
-
-### Native Gems (recommended)
-
-In v1.5.0 and later, native (precompiled) gems are available for recent Ruby versions on these platforms:
-
-- `aarch64-linux` (requires: glibc >= 2.29)
-- `arm-linux` (requires: glibc >= 2.29)
-- `arm64-darwin`
-- `x64-mingw32` / `x64-mingw-ucrt`
-- `x86-linux` (requires: glibc >= 2.17)
-- `x86_64-darwin`
-- `x86_64-linux` (requires: glibc >= 2.17)
-
-If you are using one of these Ruby versions on one of these platforms, the native gem is the recommended way to install sqlite3-ruby.
-
-For example, on a linux system running Ruby 3.1:
-
-``` text
-$ ruby -v
-ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [x86_64-linux]
-
-$ time gem install sqlite3
-Fetching sqlite3-1.5.0-x86_64-linux.gem
-Successfully installed sqlite3-1.5.0-x86_64-linux
-1 gem installed
-
-real    0m4.274s
-user    0m0.734s
-sys     0m0.165s
-```
-
-#### Avoiding the precompiled native gem
-
-The maintainers strongly urge you to use a native gem if at all possible. It will be a better experience for you and allow us to focus our efforts on improving functionality rather than diagnosing installation issues.
-
-If you're on a platform that supports a native gem but you want to avoid using it in your project, do one of the following:
-
-- If you're not using Bundler, then run `gem install sqlite3 --platform=ruby`
-- If you are using Bundler
-  - version 2.3.18 or later, you can specify [`gem "sqlite3", force_ruby_platform: true`](https://bundler.io/v2.3/man/gemfile.5.html#FORCE_RUBY_PLATFORM)
-  - version 2.1 or later, then you'll need to run `bundle config set force_ruby_platform true`
-  - version 2.0 or earlier, then you'll need to run `bundle config force_ruby_platform true`
-
-
-### Compiling the source gem
-
-If you are on a platform or version of Ruby that is not covered by the Native Gems, then the vanilla "ruby platform" (non-native) gem will be installed by the `gem install` or `bundle` commands.
-
-
-#### Packaged libsqlite3
-
-By default, as of v1.5.0 of this library, the latest available version of libsqlite3 is packaged with the gem and will be compiled and used automatically. This takes a bit longer than the native gem, but will provide a modern, well-supported version of libsqlite3.
-
-For example, on a linux system running Ruby 2.5:
-
-``` text
-$ ruby -v
-ruby 2.5.9p229 (2021-04-05 revision 67939) [x86_64-linux]
-
-$ time gem install sqlite3
-Building native extensions. This could take a while...
-Successfully installed sqlite3-1.5.0
-1 gem installed
-
-real    0m20.620s
-user    0m23.361s
-sys     0m5.839s
-```
-
-
-#### System libsqlite3
-
-If you would prefer to build the sqlite3-ruby gem against your system libsqlite3, which requires that you install libsqlite3 and its development files yourself, you may do so by using the `--enable-system-libraries` flag at gem install time.
-
-PLEASE NOTE:
-
-- you must avoid installing a precompiled native gem (see [previous section](#avoiding-the-precompiled-native-gem))
-- only versions of libsqlite3 `>= 3.5.0` are supported,
-- and some library features may depend on how your libsqlite3 was compiled.
-
-For example, on a linux system running Ruby 2.5:
-
-``` text
-$ time gem install sqlite3 -- --enable-system-libraries
-Building native extensions with: '--enable-system-libraries'
-This could take a while...
-Successfully installed sqlite3-1.5.0
-1 gem installed
-
-real    0m4.234s
-user    0m3.809s
-sys     0m0.912s
-```
-
-If you're using bundler, you can opt into system libraries like this:
-
-``` sh
-bundle config build.sqlite3 --enable-system-libraries
-```
-
-If you have sqlite3 installed in a non-standard location, you may need to specify the location of the include and lib files by using `--with-sqlite-include` and `--with-sqlite-lib` options (or a `--with-sqlite-dir` option, see [MakeMakefile#dir_config](https://ruby-doc.org/stdlib-3.1.1/libdoc/mkmf/rdoc/MakeMakefile.html#method-i-dir_config)). If you have pkg-config installed and configured properly, this may not be necessary.
-
-``` sh
-gem install sqlite3 -- \
-  --enable-system-libraries \
-  --with-sqlite3-include=/opt/local/include \
-  --with-sqlite3-lib=/opt/local/lib
-```
-
-
-#### System libsqlcipher
-
-If you'd like to link against a system-installed libsqlcipher, you may do so by using the `--with-sqlcipher` flag:
-
-``` text
-$ time gem install sqlite3 -- --with-sqlcipher
-Building native extensions with: '--with-sqlcipher'
-This could take a while...
-Successfully installed sqlite3-1.5.0
-1 gem installed
-
-real    0m4.772s
-user    0m3.906s
-sys     0m0.896s
-```
-
-If you have sqlcipher installed in a non-standard location, you may need to specify the location of the include and lib files by using `--with-sqlite-include` and `--with-sqlite-lib` options (or a `--with-sqlite-dir` option, see [MakeMakefile#dir_config](https://ruby-doc.org/stdlib-3.1.1/libdoc/mkmf/rdoc/MakeMakefile.html#method-i-dir_config)). If you have pkg-config installed and configured properly, this may not be necessary.
-
-
 ## Support
 
-### Something has gone wrong! Where do I get help?
-
-You can ask for help or support from the
-[sqlite3-ruby mailing list](http://groups.google.com/group/sqlite3-ruby) which
-can be found here:
-
-> http://groups.google.com/group/sqlite3-ruby
-
+### Installation or database extensions
 
-### I've found a bug! How do I report it?
+If you're having trouble with installation, please first read [`INSTALLATION.md`](./INSTALLATION.md).
 
-After contacting the mailing list, you've found that you've uncovered a bug. You can file the bug at the [github issues page](https://github.com/sparklemotion/sqlite3-ruby/issues) which can be found here:
+### General help requests
 
-> https://github.com/sparklemotion/sqlite3-ruby/issues
+You can ask for help or support:
 
+* by emailing the [sqlite3-ruby mailing list](http://groups.google.com/group/sqlite3-ruby)
+* by opening a [discussion thread](https://github.com/sparklemotion/sqlite3-ruby/discussions/categories/q-a) on Github
 
-## Usage
+### Bug reports
 
-For help figuring out the SQLite3/Ruby interface, check out the SYNOPSIS as well as the RDoc. It includes examples of usage. If you have any questions that you feel should be addressed in the FAQ, please send them to [the mailing list](http://groups.google.com/group/sqlite3-ruby).
+You can file the bug at the [github issues page](https://github.com/sparklemotion/sqlite3-ruby/issues).
 
 
 ## Contributing
diff --git a/sqlite3.gemspec b/sqlite3.gemspec
index 85c46e46..daf61c38 100644
--- a/sqlite3.gemspec
+++ b/sqlite3.gemspec
@@ -42,6 +42,7 @@ Gem::Specification.new do |s|
     "ChangeLog.cvs",
     "FAQ.md",
     "Gemfile",
+    "INSTALLATION.md",
     "LICENSE",
     "LICENSE-DEPENDENCIES",
     "README.md",

From a2aa21a27edb601721ec7a452052e604e1f6744d Mon Sep 17 00:00:00 2001
From: Mike Dalessio 
Date: Wed, 24 May 2023 11:41:41 -0400
Subject: [PATCH 3/3] doc: create .rdoc_options with good defaults

---
 .gitignore                  |  2 ++
 .rdoc_options               | 31 +++++++++++++++++++++++++++++++
 rakelib/check-manifest.rake |  3 +++
 3 files changed, 36 insertions(+)
 create mode 100644 .rdoc_options

diff --git a/.gitignore b/.gitignore
index b7952d5e..0c7faa30 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,7 +8,9 @@ test/test.db
 
 Gemfile.lock
 
+doc/
 gems/
+issues/
 pkg/
 ports/
 tmp/
diff --git a/.rdoc_options b/.rdoc_options
new file mode 100644
index 00000000..768e351e
--- /dev/null
+++ b/.rdoc_options
@@ -0,0 +1,31 @@
+---
+encoding: UTF-8
+static_path: []
+rdoc_include: []
+page_dir: 
+charset: UTF-8
+exclude:
+- "~\\z"
+- "\\.orig\\z"
+- "\\.rej\\z"
+- "\\.bak\\z"
+- "\\.gemspec\\z"
+- "issues"
+- "bin"
+- "rakelib"
+- "ext/sqlite3/extconf.rb"
+hyperlink_all: false
+line_numbers: false
+locale: 
+locale_dir: locale
+locale_name: 
+main_page: "README.md"
+markup: rdoc
+output_decoration: true
+show_hash: false
+skip_tests: true
+tab_width: 8
+template_stylesheets: []
+title: 
+visibility: :protected
+webcvs: 
diff --git a/rakelib/check-manifest.rake b/rakelib/check-manifest.rake
index c4826efb..33c395fd 100644
--- a/rakelib/check-manifest.rake
+++ b/rakelib/check-manifest.rake
@@ -10,7 +10,9 @@ task :check_manifest do
     .git
     .github
     bin
+    doc
     gems
+    issues
     patches
     pkg
     ports
@@ -21,6 +23,7 @@ task :check_manifest do
   }
   ignore_files = %w[
     .gitignore
+    .rdoc_options
     Gemfile?*
     Rakefile
     [a-z]*.{log,out}