From 0903df8b4fa7ed29210df9d28a4b072d589d652d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Rombauts?= Date: Thu, 30 Jan 2020 21:12:26 +0100 Subject: [PATCH] Add a docs/ directory with a copy of the README.md for Github web page --- docs/README.md | 323 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 323 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..a4d9c88 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,323 @@ +SQLiteC++ +--------- + +[![release](https://img.shields.io/github/release/SRombauts/SQLiteCpp.svg)](https://github.com/SRombauts/SQLiteCpp/releases) +[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/SRombauts/SQLiteCpp/blob/master/LICENSE.txt) +[![Travis CI Linux Build Status](https://travis-ci.org/SRombauts/SQLiteCpp.svg?branch=master)](https://travis-ci.org/SRombauts/SQLiteCpp "Travis CI Linux Build Status") +[![AppVeyor Windows Build status](https://ci.appveyor.com/api/projects/status/github/SRombauts/SQLiteCpp?svg=true)](https://ci.appveyor.com/project/SbastienRombauts/SQLiteCpp "AppVeyor Windows Build status") +[![GitHub Actions Build status](https://github.com/SRombauts/SQLiteCpp/workflows/build/badge.svg)](https://github.com/SRombauts/SQLiteCpp/actions "GitHhub Actions Build status") +[![Coveralls](https://img.shields.io/coveralls/SRombauts/SQLiteCpp.svg)](https://coveralls.io/github/SRombauts/SQLiteCpp "Coveralls test coverage") +[![Coverity](https://img.shields.io/coverity/scan/14508.svg)](https://scan.coverity.com/projects/srombauts-sqlitecpp "Coverity Scan Build Status") +[![Join the chat at https://gitter.im/SRombauts/SQLiteCpp](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/SRombauts/SQLiteCpp?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) + +SQLiteC++ (SQLiteCpp) is a smart and easy to use C++ SQLite3 wrapper. + +Keywords: sqlite, sqlite3, C, library, wrapper C++ + +## About SQLiteC++: + +SQLiteC++ offers an encapsulation around the native C APIs of SQLite, +with a few intuitive and well documented C++ classes. + +### License: + +Copyright (c) 2012-2020 Sébastien Rombauts (sebastien.rombauts@gmail.com) + + +Distributed under the MIT License (MIT) (See accompanying file LICENSE.txt +or copy at http://opensource.org/licenses/MIT) + +#### Note on redistribution of SQLite source files + +As stated by the MIT License, you are welcome to reuse, modify, and redistribute the SQLiteCpp source code +the way you want it to, be it a git submodule, a subdirectory, or a selection of some source files. + +I would love a mention in your README, a web link to the SQLite repository, and a mention of the author, +but none of those are mandatory. + +### About SQLite underlying library: + +SQLite is a library that implements a serverless transactional SQL database engine. +It is the most widely deployed SQL database engine in the world. +All of the code and documentation in SQLite has been dedicated to the public domain by the authors. +http://www.sqlite.org/about.html + +### The goals of SQLiteC++ are: + +- to offer the best of the existing simple C++ SQLite wrappers +- to be elegantly written with good C++11 design, STL, exceptions and RAII idiom +- to keep dependencies to a minimum (C++11 STL and SQLite3) +- to be portable +- to be light and fast +- to be thread-safe only as much as SQLite "Multi-thread" mode (see below) +- to have a good unit test coverage +- to use API names sticking with those of the SQLite library +- to be well documented with Doxygen tags, and with some good examples +- to be well maintained +- to use a permissive MIT license, similar to BSD or Boost, for proprietary/commercial usage + +It is designed using the Resource Acquisition Is Initialization (RAII) idiom +(see http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization), +and throwing exceptions in case of SQLite errors (except in destructors, +where assert() are used instead). +Each SQLiteC++ object must be constructed with a valid SQLite database connection, +and then is always valid until destroyed. + +### Supported platforms: + +Now requires a C++11 compiler. Use branch [sqlitecpp-2.x](https://github.com/SRombauts/SQLiteCpp/tree/sqlitecpp-2.x) for latest pre-C++11 developments. + +Developments and tests are done under the following OSs: +- Ubuntu 14.04, 16.04 and 18.04 (Travis CI) +- Windows 10, and Windows Server 2012 R2 & Windows Server 2016 (AppVeyor) +- OS X 10.11 (Travis CI) +- Github Actions +- Valgrind memcheck tool + +And the following IDEs/Compilers +- GCC 4.8.4, 5.3.0 and 7.1.1 (C++11, C++14, C++17) +- Clang 5 +- Xcode 8 & 9 +- Visual Studio Community 2019, 2017, and 2015 (AppVeyor) + +### Dependencies + +- a modern C++11 STL implementation with GCC, Clang, or Visual Studio 2015 +- exception support (the class Exception inherits from std::runtime_error) +- the SQLite library (3.7.15 minimum from 2012-12-12) either by linking to it dynamically or statically (install the libsqlite3-dev package under Debian/Ubuntu/Mint Linux), + or by adding its source file in your project code base (source code provided in src/sqlite3 for Windows), + with the SQLITE_ENABLE_COLUMN_METADATA macro defined (see http://www.sqlite.org/compile.html#enable_column_metadata). + +## Getting started +### Installation + +To use this wrapper, you need to add the SQLiteC++ source files from the src/ directory +in your project code base, and compile/link against the sqlite library. + +The easiest way to do this is to add the wrapper as a library. +The "CMakeLists.txt" file defining the static library is provided in the root directory, +so you simply have to add_subdirectory(SQLiteCpp) to you main CMakeLists.txt +and link to the "SQLiteCpp" wrapper library. + +Example for Linux: +```cmake +add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/thirdparty/SQLiteCpp) + +include_directories( + ${CMAKE_CURRENT_LIST_DIR}/thirdparty/SQLiteCpp/include +) + +add_executable(main src/main.cpp) +target_link_libraries(main + SQLiteCpp + sqlite3 + pthread + dl + ) +``` +Thus this SQLiteCpp repository can be directly used as a Git submodule. +See the [SQLiteCpp_Example](https://github.com/SRombauts/SQLiteCpp_Example) side repository for a standalone "from scratch" example. + +Under Debian/Ubuntu/Mint Linux, you can install the libsqlite3-dev package if you don't want to use the embedded sqlite3 library. + +### Building example and unit-tests: + +Use git to clone the repository. Then init and update submodule "googletest". + +```Shell +git clone https://github.com/SRombauts/SQLiteCpp.git +cd SQLiteCpp +git submodule init +git submodule update +``` + +#### CMake and tests +A CMake configuration file is also provided for multi-platform support and testing. + +Typical generic build for MS Visual Studio under Windows (from [build.bat](build.bat)): + +```Batchfile +mkdir build +cd build + +cmake .. # cmake .. -G "Visual Studio 16 2019" # for Visual Studio 2019 +@REM Generate a Visual Studio solution for latest version found +cmake -DSQLITECPP_BUILD_EXAMPLES=ON -DSQLITECPP_BUILD_TESTS=ON .. + +@REM Build default configuration (ie 'Debug') +cmake --build . + +@REM Build and run tests +ctest --output-on-failure +``` + +Generating the Linux Makefile, building in Debug and executing the tests (from [build.sh](build.sh)): + +```Shell +mkdir Debug +cd Debug + +# Generate a Makefile for GCC (or Clang, depanding on CC/CXX envvar) +cmake -DSQLITECPP_BUILD_EXAMPLES=ON -DSQLITECPP_BUILD_TESTS=ON .. + +# Build (ie 'make') +cmake --build . + +# Build and run unit-tests (ie 'make test') +ctest --output-on-failure +``` + +#### CMake options + + * For more options on customizing the build, see the [CMakeLists.txt](https://github.com/SRombauts/SQLiteCpp/blob/master/CMakeLists.txt) file. + +#### Troubleshooting + +Under Linux, if you get multiple linker errors like "undefined reference to sqlite3_xxx", +it's that you lack the "sqlite3" library: install the libsqlite3-dev package. + +If you get a single linker error "Column.cpp: undefined reference to sqlite3_column_origin_name", +it's that your "sqlite3" library was not compiled with +the SQLITE_ENABLE_COLUMN_METADATA macro defined (see http://www.sqlite.org/compile.html#enable_column_metadata). +You can either recompile it yourself (seek help online) or you can comment out the following line in src/Column.h: + +```C++ +#define SQLITE_ENABLE_COLUMN_METADATA +``` + +### Continuous Integration + +This project is continuously tested under Ubuntu Linux with the gcc and clang compilers +using the Travis CI community service with the above CMake building and testing procedure. +It is also tested in the same way under Windows Server 2012 R2 with Visual Studio 2013 compiler +using the AppVeyor continuous integration service. + +Detailed results can be seen online: + - https://travis-ci.org/SRombauts/SQLiteCpp + - https://ci.appveyor.com/project/SbastienRombauts/SQLiteCpp + +### Thread-safety + +SQLite supports three modes of thread safety, as describe in "SQLite And Multiple Threads": +see http://www.sqlite.org/threadsafe.html + +This SQLiteC++ wrapper does no add any locks (no mutexes) nor any other thread-safety mechanism +above the SQLite library itself, by design, for lightness and speed. + +Thus, SQLiteC++ naturally supports the "Multi Thread" mode of SQLite: +"In this mode, SQLite can be safely used by multiple threads +provided that no single database connection is used simultaneously in two or more threads." + +But SQLiteC++ does not support the fully thread-safe "Serialized" mode of SQLite, +because of the way it shares the underlying SQLite precompiled statement +in a custom shared pointer (See the inner class "Statement::Ptr"). + +## Examples +### The first sample demonstrates how to query a database and get results: + +```C++ +try +{ + // Open a database file + SQLite::Database db("example.db3"); + + // Compile a SQL query, containing one parameter (index 1) + SQLite::Statement query(db, "SELECT * FROM test WHERE size > ?"); + + // Bind the integer value 6 to the first parameter of the SQL query + query.bind(1, 6); + + // Loop to execute the query step by step, to get rows of result + while (query.executeStep()) + { + // Demonstrate how to get some typed column value + int id = query.getColumn(0); + const char* value = query.getColumn(1); + int size = query.getColumn(2); + + std::cout << "row: " << id << ", " << value << ", " << size << std::endl; + } +} +catch (std::exception& e) +{ + std::cout << "exception: " << e.what() << std::endl; +} +``` + +### The second sample shows how to manage a transaction: + +```C++ +try +{ + SQLite::Database db("transaction.db3", SQLite::OPEN_READWRITE|SQLite::OPEN_CREATE); + + db.exec("DROP TABLE IF EXISTS test"); + + // Begin transaction + SQLite::Transaction transaction(db); + + db.exec("CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)"); + + int nb = db.exec("INSERT INTO test VALUES (NULL, \"test\")"); + std::cout << "INSERT INTO test VALUES (NULL, \"test\")\", returned " << nb << std::endl; + + // Commit transaction + transaction.commit(); +} +catch (std::exception& e) +{ + std::cout << "exception: " << e.what() << std::endl; +} +``` + +### How to handle assertion in SQLiteC++: +Exceptions shall not be used in destructors, so SQLiteC++ uses SQLITECPP_ASSERT() to check for errors in destructors. +If you don't want assert() to be called, you have to enable and define an assert handler as shown below, +and by setting the flag SQLITECPP_ENABLE_ASSERT_HANDLER when compiling the lib. + +```C++ +#ifdef SQLITECPP_ENABLE_ASSERT_HANDLER +namespace SQLite +{ +/// definition of the assertion handler enabled when SQLITECPP_ENABLE_ASSERT_HANDLER is defined in the project (CMakeList.txt) +void assertion_failed(const char* apFile, const long apLine, const char* apFunc, const char* apExpr, const char* apMsg) +{ + // Print a message to the standard error output stream, and abort the program. + std::cerr << apFile << ":" << apLine << ":" << " error: assertion failed (" << apExpr << ") in " << apFunc << "() with message \"" << apMsg << "\"\n"; + std::abort(); +} +} +#endif +``` + +## How to contribute +### GitHub website +The most efficient way to help and contribute to this wrapper project is to +use the tools provided by GitHub: +- please fill bug reports and feature requests here: https://github.com/SRombauts/SQLiteCpp/issues +- fork the repository, make some small changes and submit them with pull-request + +### Contact +You can also email me directly, I will try to answer questions and requests whenever I get the time for it. + +### Coding Style Guidelines +The source code use the CamelCase naming style variant where: +- type names (class, struct, typedef, enums...) begin with a capital letter +- files (.cpp/.h) are named like the class they contain +- function and variable names begin with a lower case letter +- member variables begin with a 'm', function arguments begin with a 'a', booleans with a 'b', pointers with a 'p' +- each file, class, method and member variable is documented using Doxygen tags +- braces on their own line +See also http://www.appinf.com/download/CppCodingStyleGuide.pdf for good guidelines + +## See also - Some other simple C++ SQLite wrappers: + +See bellow a short comparison of other wrappers done at the time of writing: + - [sqdbcpp](http://code.google.com/p/sqdbcpp/): RAII design, simple, no dependencies, UTF-8/UTF-16, new BSD license + - [sqlite3cc](http://ed.am/dev/sqlite3cc): uses boost, modern design, LPGPL + - [sqlite3pp](https://github.com/iwongu/sqlite3pp): modern design inspired by boost, MIT License + - [SQLite++](http://sqlitepp.berlios.de/): uses boost build system, Boost License 1.0 + - [CppSQLite](http://www.codeproject.com/Articles/6343/CppSQLite-C-Wrapper-for-SQLite/): famous Code Project but old design, BSD License + - [easySQLite](http://code.google.com/p/easysqlite/): manages table as structured objects, complex + - [sqlite_modern_cpp](https://github.com/keramer/sqlite_modern_cpp): modern C++11, all in one file, MIT license + - [sqlite_orm](https://github.com/fnc12/sqlite_orm): modern C++14, header only all in one file, no raw string queries, BSD-3 license