From 823026b58211a4166de06ac243d978dcb9930271 Mon Sep 17 00:00:00 2001 From: Karen Arutyunov Date: Mon, 22 Jan 2024 15:58:08 +0300 Subject: Turn odb repository into muti-package repository Also remove the autoconf/make-based build system. --- doc/pregenerated/odb.1 | 799 ------------------------------------ doc/pregenerated/odb.xhtml | 978 --------------------------------------------- 2 files changed, 1777 deletions(-) delete mode 100644 doc/pregenerated/odb.1 delete mode 100644 doc/pregenerated/odb.xhtml (limited to 'doc/pregenerated') diff --git a/doc/pregenerated/odb.1 b/doc/pregenerated/odb.1 deleted file mode 100644 index 42d81d0..0000000 --- a/doc/pregenerated/odb.1 +++ /dev/null @@ -1,799 +0,0 @@ -.\" Process this file with -.\" groff -man -Tascii odb.1 -.\" -.TH ODB 1 "February 2015" "ODB 2.4.0" -.SH NAME -odb \- object-relational mapping (ORM) compiler for C++ -.\" -.\" -.\" -.\"-------------------------------------------------------------------- -.SH SYNOPSIS -.\"-------------------------------------------------------------------- -.B odb -.B [ -.I options -.B ] -.I file -.B [ -.IR file... -.B ] -.\" -.\" -.\" -.\"-------------------------------------------------------------------- -.SH DESCRIPTION -.\"-------------------------------------------------------------------- -Given a set of C++ classes in a header file, -.B odb -generates C++ code that allows you to persist, query, and update objects -of these classes in a relational database (RDBMS). The relational -database that the generated code should target is specified with the -required -.B --database -option (see below). - - -For an input file in the form -.B name.hxx -(other file extensions can be used instead of -.BR .hxx ), -in the single-database mode (the default), the generated C++ files by -default have the following names: -.B name-odb.hxx -(header file), -.B name-odb.ixx -(inline file), and -.B name-odb.cxx -(source file). Additionally, if the -.B --generate-schema -option is specified and the -.B sql -schema format is requested (see -.BR --schema-format ), -the -.B name.sql -database schema file is generated. If the -.B separate -schema format is requested, the database creation code is generated into -the separate -.B name-schema.cxx -file. - - -In the multi-database mode (see the -.B --multi-database -option below), the generated files corresponding to the -.B common -database have the same names as in the single-database mode. For other -databases, the file names include the database name: -.BR name-odb-\fIdb\fB.hxx , -.BR name-odb-\fIdb\fB.ixx , -.BR name-odb-\fIdb\fB.cxx , -.BR name-\fIdb\fB.sql , -and -.B name-schema-\fIdb\fB.cxx -(where -.I db -is the database name). -.\" -.\" -.\" -.\"-------------------------------------------------------------------- -.SH OPTIONS -.\"-------------------------------------------------------------------- -.IP "\fB--help\fR" -Print usage information and exit\. -.IP "\fB--version\fR" -Print version and exit\. -.IP "\fB-I\fR \fIdir\fR" -Add \fIdir\fR to the beginning of the list of directories to be searched for -included header files\. -.IP "\fB-D\fR \fIname\fR[=\fIdef\fR]" -Define macro \fIname\fR with definition \fIdef\fR\. If definition is omitted, -define \fIname\fR to be 1\. -.IP "\fB-U\fR \fIname\fR" -Cancel any previous definitions of macro \fIname\fR, either built-in or -provided with the \fB-D\fR option\. -.IP "\fB--database\fR|\fB-d\fR \fIdb\fR" -Generate code for the \fIdb\fR database\. Valid values are \fBmssql\fR, -\fBmysql\fR, \fBoracle\fR, \fBpgsql\fR, \fBsqlite\fR, and \fBcommon\fR -(multi-database mode only)\. -.IP "\fB--multi-database\fR|\fB-m\fR \fItype\fR" -Enable multi-database support and specify its type\. Valid values for this -option are \fBstatic\fR and \fBdynamic\fR\. - -In the multi-database mode, options that determine the kind (for example, -\fB--schema-format\fR), names (for example, \fB--odb-file-suffix\fR), or -content (for example, prologue and epilogue options) of the output files can -be prefixed with the database name followed by a colon, for example, -\fBmysql:value\fR\. This restricts the value of such an option to only apply -to generated files corresponding to this database\. -.IP "\fB--default-database\fR \fIdb\fR" -When static multi-database support is used, specify the database that should -be made the default\. When dynamic multi-database support is used, -\fBcommon\fR is always made the default database\. -.IP "\fB--generate-query\fR|\fB-q\fR" -Generate query support code\. Without this support you cannot use views and -can only load objects via their ids\. -.IP "\fB--generate-prepared\fR" -Generate prepared query execution support code\. -.IP "\fB--omit-unprepared\fR" -Omit un-prepared (once-off) query execution support code\. -.IP "\fB--generate-session\fR|\fB-e\fR" -Generate session support code\. With this option session support will be -enabled by default for all the persistent classes except those for which it -was explicitly disabled using the \fBdb session\fR pragma\. -.IP "\fB--generate-schema\fR|\fB-s\fR" -Generate the database schema\. The database schema contains SQL statements -that create database tables necessary to store persistent classes defined in -the file being compiled\. Note that by applying this schema, all the existing -information stored in such tables will be lost\. - -Depending on the database being used (\fB--database\fR option), the schema is -generated either as a standalone SQL file or embedded into the generated C++ -code\. By default the SQL file is generated for the MySQL, PostgreSQL, Oracle, -and Microsoft SQL Server databases and the schema is embedded into the C++ -code for the SQLite database\. Use the \fB--schema-format\fR option to alter -the default schema format\. - -If database schema evolution support is enabled (that is, the object model -version is specified), then this option also triggers the generation of -database schema migration statements, again either as standalong SQL files or -embedded into the generated C++ code\. You can suppress the generation of -schema migration statements by specifying the \fB--suppress-migration\fR -option\. -.IP "\fB--generate-schema-only\fR" -Generate only the database schema\. Note that this option is only valid when -generating schema as a standalone SQL file (see \fB--schema-format\fR for -details)\. -.IP "\fB--suppress-migration\fR" -Suppress the generation of database schema migration statements\. -.IP "\fB--suppress-schema-version\fR" -Suppress the generation of schema version table\. If you specify this option -then you are also expected to manually specify the database schema version and -migration state at runtime using the \fBodb::database::schema_version()\fR -function\. -.IP "\fB--schema-version-table\fR \fIname\fR" -Specify the alternative schema version table name instead of the default -\fBschema_version\fR\. If you specify this option then you are also expected -to manually specify the schema version table name at runtime using the -\fBodb::database::schema_version_table()\fR function\. The table name can be -qualified\. -.IP "\fB--schema-format\fR \fIformat\fR" -Generate the database schema in the specified format\. Pass \fBsql\fR as -\fIformat\fR to generate the database schema as a standalone SQL file or pass -\fBembedded\fR to embed the schema into the generated C++ code\. The -\fBseparate\fR value is similar to \fBembedded\fR except the schema creation -code is generated into a separate C++ file (\fBname-schema\.cxx\fR by -default)\. This value is primarily useful if you want to place the schema -creation functionality into a separate program or library\. Repeat this option -to generate the same database schema in multiple formats\. -.IP "\fB--omit-drop\fR" -Omit \fBDROP\fR statements from the generated database schema\. -.IP "\fB--omit-create\fR" -Omit \fBCREATE\fR statements from the generated database schema\. -.IP "\fB--schema-name\fR \fIname\fR" -Use \fIname\fR as the database schema name\. Schema names are primarily used -to distinguish between multiple embedded schemas in the schema catalog\. They -are not to be confused with database schemas (database namespaces) which are -specified with the \fB--schema\fR option\. If this option is not specified, -the empty name, which is the default schema name, is used\. -.IP "\fB--fkeys-deferrable-mode\fR \fIm\fR" -Use constraint checking mode \fIm\fR in foreign keys generated for object -relationships\. Valid values for this option are \fBnot_deferrable\fR, -\fBimmediate\fR, and \fBdeferred\fR (default)\. MySQL and SQL Server do not -support deferrable foreign keys and for these databases such keys are -generated commented out\. Other foreign keys generated by the ODB compiler -(such as the ones used to support containers and polymorphic hierarchies) are -always generated as not deferrable\. - -Note also that if you use either \fBnot_deferrable\fR or \fBimmediate\fR mode, -then the order in which you persist, update, and erase objects within a -transaction becomes important\. -.IP "\fB--default-pointer\fR \fIptr\fR" -Use \fIptr\fR as the default pointer for persistent objects and views\. -Objects and views that do not have a pointer assigned with the \fBdb -pointer\fR pragma will use this pointer by default\. The value of this option -can be '\fB*\fR' which denotes the raw pointer and is the default, or -qualified name of a smart pointer class template, for example, -\fBstd::shared_ptr\fR\. In the latter case, the ODB compiler constructs the -object or view pointer by adding a single template argument of the object or -view type to the qualified name, for example \fBstd::shared_ptr\fR\. -The ODB runtime uses object and view pointers to return, and, in case of -objects, pass and cache dynamically allocated instances of object and view -types\. - -Except for the raw pointer and the standard smart pointers defined in the -\fB\fR header file, you are expected to include the definition of the -default pointer at the beginning of the generated header file\. There are two -common ways to achieve this: you can either include the necessary header in -the file being compiled or you can use the \fB--hxx-prologue\fR option to add -the necessary \fB#include\fR directive to the generated code\. -.IP "\fB--session-type\fR \fItype\fR" -Use \fItype\fR as the alternative session type instead of the default -\fBodb::session\fR\. This option can be used to specify a custom session -implementation to be use by the persistent classes\. Note that you will also -need to include the definition of the custom session type into the generated -header file\. This is normally achieved with the \fB--hxx-prologue*\fR -options\. -.IP "\fB--profile\fR|\fB-p\fR \fIname\fR" -Specify a profile that should be used during compilation\. A profile is an -options file\. The ODB compiler first looks for a database-specific version -with the name constructed by appending the -\fB-\fR\fIdatabase\fR\fB\.options\fR suffix to \fIname\fR, where -\fIdatabase\fR is the database name as specified with the \fB--database\fR -option\. If this file is not found, then the ODB compiler looks for a -database-independant version with the name constructed by appending just the -\fB\.options\fR suffix\. - -The profile options files are searched for in the same set of directories as -C++ headers included with the \fB#include <\.\.\.>\fR directive (built-in -paths plus those specified with the \fB-I\fR options)\. The options file is -first searched for in the directory itself and then in its \fBodb/\fR -subdirectory\. - -For the format of the options file refer to the \fB--options-file\fR option -below\. You can repeat this option to specify more than one profile\. -.IP "\fB--at-once\fR" -Generate code for all the input files as well as for all the files that they -include at once\. The result is a single set of source/schema files that -contain all the generated code\. If more than one input file is specified -together with this option, then the \fB--input-name\fR option must also be -specified in order to provide the base name for the output files\. In this -case, the directory part of such a base name is used as the location of the -combined file\. This can be important for the \fB#include\fR directive -resolution\. -.IP "\fB--schema\fR \fIschema\fR" -Specify a database schema (database namespace) that should be assigned to the -persistent classes in the file being compiled\. Database schemas are not to be -confused with database schema names (schema catalog names) which are specified -with the \fB--schema-name\fR option\. -.IP "\fB--export-symbol\fR \fIsymbol\fR" -Insert \fIsymbol\fR in places where DLL export/import control statements -(\fB__declspec(dllexport/dllimport)\fR) are necessary\. See also the -\fB--extern-symbol\fR option below\. -.IP "\fB--extern-symbol\fR \fIsymbol\fR" -If \fIsymbol\fR is defined, insert it in places where a template instantiation -must be declared \fBextern\fR\. This option is normally used together with -\fB--export-symbol\fR when both multi-database support and queries are -enabled\. -.IP "\fB--std\fR \fIversion\fR" -Specify the C++ standard that should be used during compilation\. Valid values -are \fBc++98\fR (default), \fBc++11\fR, \fBc++14\fR, \fBc++17\fR, and -\fBc++20\fR\. -.IP "\fB--warn-hard-add\fR" -Warn about hard-added data members\. -.IP "\fB--warn-hard-delete\fR" -Warn about hard-deleted data members and persistent classes\. -.IP "\fB--warn-hard\fR" -Warn about both hard-added and hard-deleted data members and persistent -classes\. -.IP "\fB--output-dir\fR|\fB-o\fR \fIdir\fR" -Write the generated files to \fIdir\fR instead of the current directory\. -.IP "\fB--input-name\fR \fIname\fR" -Use \fIname\fR instead of the input file to derive the names of the generated -files\. If the \fB--at-once\fR option is specified, then the directory part of -\fIname\fR is used as the location of the combined file\. Refer to the -\fB--at-once\fR option for details\. -.IP "\fB--changelog\fR \fIfile\fR" -Read/write changelog from/to \fIfile\fR instead of the default changelog -file\. The default changelog file name is derived from the input file name and -it is placed into the same directory as the input file\. Note that the -\fB--output-dir\fR option does not affect the changelog file location\. In -other words, by default, the changelog file is treated as another input rather -than output even though the ODB compiler may modify it\. Use the -\fB--changelog-in\fR and \fB--changelog-out\fR options to specify different -input and output chaneglog files\. -.IP "\fB--changelog-in\fR \fIfile\fR" -Read changelog from \fIfile\fR instead of the default changelog file\. If this -option is specified, then you must also specify the output chanegelog file -with \fB--changelog-out\fR\. -.IP "\fB--changelog-out\fR \fIfile\fR" -Write changelog to \fIfile\fR instead of the default changelog file\. If this -option is specified, then you must also specify the input chanegelog file with -\fB--changelog-in\fR\. -.IP "\fB--changelog-dir\fR \fIdir\fR" -Use \fIdir\fR instead of the input file directory as the changelog file -directory\. This directory is also added to changelog files specified with the -\fB--changelog\fR, \fB--changelog-in\fR, and \fB--changelog-in\fR options -unless they are absolute paths\. -.IP "\fB--init-changelog\fR" -Force re-initialization of the changelog even if one exists (all the existing -change history will be lost)\. This option is primarily useful for automated -testing\. -.IP "\fB--odb-file-suffix\fR \fIsuffix\fR" -Use \fIsuffix\fR to construct the names of the generated C++ files\. In the -single-database mode the default value for this option is \fB-odb\fR\. In the -multi-database mode it is \fB-odb\fR for the files corresponding to the -\fBcommon\fR database and \fB-odb-\fR\fIdb\fR\fR (where \fIdb\fR is the -database name) for other databases\. -.IP "\fB--sql-file-suffix\fR \fIsuffix\fR" -Use \fIsuffix\fR to construct the name of the generated schema SQL file\. In -the single-database mode by default no suffix is used\. In the multi-database -mode the default value for this option is \fB-\fR\fIdb\fR\fR (where \fIdb\fR -is the database name)\. -.IP "\fB--schema-file-suffix\fR \fIsuffix\fR" -Use \fIsuffix\fR to construct the name of the generated schema C++ source -file\. In the single-database mode the default value for this option is -\fB-schema\fR\. In the multi-database mode it is \fB-schema-\fR\fIdb\fR\fR -(where \fIdb\fR is the database name)\. See the \fB--schema-format\fR option -for details\. -.IP "\fB--changelog-file-suffix\fR \fIsfx\fR" -Use \fIsfx\fR to construct the name of the changelog file\. In the -single-database mode by default no suffix is used\. In the multi-database mode -the default value for this option is \fB-\fR\fIdb\fR\fR (where \fIdb\fR is the -database name)\. -.IP "\fB--hxx-suffix\fR \fIsuffix\fR" -Use \fIsuffix\fR instead of the default \fB\.hxx\fR to construct the name of -the generated C++ header file\. -.IP "\fB--ixx-suffix\fR \fIsuffix\fR" -Use \fIsuffix\fR instead of the default \fB\.ixx\fR to construct the name of -the generated C++ inline file\. -.IP "\fB--cxx-suffix\fR \fIsuffix\fR" -Use \fIsuffix\fR instead of the default \fB\.cxx\fR to construct the name of -the generated C++ source file\. -.IP "\fB--sql-suffix\fR \fIsuffix\fR" -Use \fIsuffix\fR instead of the default \fB\.sql\fR to construct the name of -the generated database schema file\. -.IP "\fB--changelog-suffix\fR \fIsuffix\fR" -Use \fIsuffix\fR instead of the default \fB\.xml\fR to construct the name of -the changelog file\. -.IP "\fB--hxx-prologue\fR \fItext\fR" -Insert \fItext\fR at the beginning of the generated C++ header file\. -.IP "\fB--ixx-prologue\fR \fItext\fR" -Insert \fItext\fR at the beginning of the generated C++ inline file\. -.IP "\fB--cxx-prologue\fR \fItext\fR" -Insert \fItext\fR at the beginning of the generated C++ source file\. -.IP "\fB--schema-prologue\fR \fItext\fR" -Insert \fItext\fR at the beginning of the generated schema C++ source file\. -.IP "\fB--sql-prologue\fR \fItext\fR" -Insert \fItext\fR at the beginning of the generated database schema file\. -.IP "\fB--migration-prologue\fR \fItext\fR" -Insert \fItext\fR at the beginning of the generated database migration file\. -.IP "\fB--sql-interlude\fR \fItext\fR" -Insert \fItext\fR after all the \fBDROP\fR and before any \fBCREATE\fR -statements in the generated database schema file\. -.IP "\fB--hxx-epilogue\fR \fItext\fR" -Insert \fItext\fR at the end of the generated C++ header file\. -.IP "\fB--ixx-epilogue\fR \fItext\fR" -Insert \fItext\fR at the end of the generated C++ inline file\. -.IP "\fB--cxx-epilogue\fR \fItext\fR" -Insert \fItext\fR at the end of the generated C++ source file\. -.IP "\fB--schema-epilogue\fR \fItext\fR" -Insert \fItext\fR at the end of the generated schema C++ source file\. -.IP "\fB--sql-epilogue\fR \fItext\fR" -Insert \fItext\fR at the end of the generated database schema file\. -.IP "\fB--migration-epilogue\fR \fItext\fR" -Insert \fItext\fR at the end of the generated database migration file\. -.IP "\fB--hxx-prologue-file\fR \fIfile\fR" -Insert the content of \fIfile\fR at the beginning of the generated C++ header -file\. -.IP "\fB--ixx-prologue-file\fR \fIfile\fR" -Insert the content of \fIfile\fR at the beginning of the generated C++ inline -file\. -.IP "\fB--cxx-prologue-file\fR \fIfile\fR" -Insert the content of \fIfile\fR at the beginning of the generated C++ source -file\. -.IP "\fB--schema-prologue-file\fR \fIfile\fR" -Insert the content of \fIfile\fR at the beginning of the generated schema C++ -source file\. -.IP "\fB--sql-prologue-file\fR \fIfile\fR" -Insert the content of \fIfile\fR at the beginning of the generated database -schema file\. -.IP "\fB--migration-prologue-file\fR \fIf\fR" -Insert the content of file \fIf\fR at the beginning of the generated database -migration file\. -.IP "\fB--sql-interlude-file\fR \fIfile\fR" -Insert the content of \fIfile\fR after all the \fBDROP\fR and before any -\fBCREATE\fR statements in the generated database schema file\. -.IP "\fB--hxx-epilogue-file\fR \fIfile\fR" -Insert the content of \fIfile\fR at the end of the generated C++ header file\. -.IP "\fB--ixx-epilogue-file\fR \fIfile\fR" -Insert the content of \fIfile\fR at the end of the generated C++ inline file\. -.IP "\fB--cxx-epilogue-file\fR \fIfile\fR" -Insert the content of \fIfile\fR at the end of the generated C++ source file\. -.IP "\fB--schema-epilogue-file\fR \fIfile\fR" -Insert the content of \fIfile\fR at the end of the generated schema C++ source -file\. -.IP "\fB--sql-epilogue-file\fR \fIfile\fR" -Insert the content of \fIfile\fR at the end of the generated database schema -file\. -.IP "\fB--migration-epilogue-file\fR \fIf\fR" -Insert the content of file \fIf\fR at the end of the generated database -migration file\. -.IP "\fB--odb-prologue\fR \fItext\fR" -Compile \fItext\fR before the input header file\. This option allows you to -add additional declarations, such as custom traits specializations, to the ODB -compilation process\. -.IP "\fB--odb-prologue-file\fR \fIfile\fR" -Compile \fIfile\fR contents before the input header file\. Prologue files are -compiled after all the prologue text fragments (\fB--odb-prologue\fR option)\. -.IP "\fB--odb-epilogue\fR \fItext\fR" -Compile \fItext\fR after the input header file\. This option allows you to add -additional declarations, such as custom traits specializations, to the ODB -compilation process\. -.IP "\fB--odb-epilogue-file\fR \fIfile\fR" -Compile \fIfile\fR contents after the input header file\. Epilogue files are -compiled after all the epilogue text fragments (\fB--odb-epilogue\fR option)\. -.IP "\fB--table-prefix\fR \fIprefix\fR" -Add \fIprefix\fR to table names and, for databases that have global index -and/or foreign key names, to those names as well\. The prefix is added to both -names that were specified with the \fBdb table\fR and \fBdb index\fR pragmas -and those that were automatically derived from class and data member names\. -If you require a separator, such as an underscore, between the prefix and the -name, then you should include it into the prefix value\. -.IP "\fB--index-suffix\fR \fIsuffix\fR" -Use \fIsuffix\fR instead of the default \fB_i\fR to construct index names\. -The suffix is only added to names that were automatically derived from data -member names\. If you require a separator, such as an underscore, between the -name and the suffix, then you should include it into the suffix value\. -.IP "\fB--fkey-suffix\fR \fIsuffix\fR" -Use \fIsuffix\fR instead of the default \fB_fk\fR to construct foreign key -names\. If you require a separator, such as an underscore, between the name -and the suffix, then you should include it into the suffix value\. -.IP "\fB--sequence-suffix\fR \fIsuffix\fR" -Use \fIsuffix\fR instead of the default \fB_seq\fR to construct sequence -names\. If you require a separator, such as an underscore, between the name -and the suffix, then you should include it into the suffix value\. -.IP "\fB--sql-name-case\fR \fIcase\fR" -Convert all automatically-derived SQL names to upper or lower case\. Valid -values for this option are \fBupper\fR and \fBlower\fR\. -.IP "\fB--table-regex\fR \fIregex\fR" -Add \fIregex\fR to the list of regular expressions that is used to transform -automatically-derived table names\. See the SQL NAME TRANSFORMATIONS section -below for details\. -.IP "\fB--column-regex\fR \fIregex\fR" -Add \fIregex\fR to the list of regular expressions that is used to transform -automatically-derived column names\. See the SQL NAME TRANSFORMATIONS section -below for details\. -.IP "\fB--index-regex\fR \fIregex\fR" -Add \fIregex\fR to the list of regular expressions that is used to transform -automatically-derived index names\. See the SQL NAME TRANSFORMATIONS section -below for details\. -.IP "\fB--fkey-regex\fR \fIregex\fR" -Add \fIregex\fR to the list of regular expressions that is used to transform -automatically-derived foreign key names\. See the SQL NAME TRANSFORMATIONS -section below for details\. -.IP "\fB--sequence-regex\fR \fIregex\fR" -Add \fIregex\fR to the list of regular expressions that is used to transform -automatically-derived sequence names\. See the SQL NAME TRANSFORMATIONS -section below for details\. -.IP "\fB--statement-regex\fR \fIregex\fR" -Add \fIregex\fR to the list of regular expressions that is used to transform -automatically-derived prepared statement names\. See the SQL NAME -TRANSFORMATIONS section below for details\. -.IP "\fB--sql-name-regex\fR \fIregex\fR" -Add \fIregex\fR to the list of regular expressions that is used to transform -all automatically-derived SQL names\. See the SQL NAME TRANSFORMATIONS section -below for details\. -.IP "\fB--sql-name-regex-trace\fR" -Trace the process of applying regular expressions specified with the SQL name -\fB--*-regex\fR options\. Use this option to find out why your regular -expressions don't do what you expected them to do\. -.IP "\fB--accessor-regex\fR \fIregex\fR" -Add \fIregex\fR to the list of regular expressions used to transform data -member names to function names when searching for a suitable accessor -function\. The argument to this option is a Perl-like regular expression in -the form \fB/\fR\fIpattern\fR\fB/\fR\fIreplacement\fR\fB/\fR\fR\. Any -character can be used as a delimiter instead of '\fB/\fR' and the delimiter -can be escaped inside \fIpattern\fR and \fIreplacement\fR with a backslash -(\fB\e\fR)\. You can specify multiple regular expressions by repeating this -option\. - -All the regular expressions are tried in the order specified and the first -expression that produces a suitable accessor function is used\. Each -expression is tried twice: first with the actual member name and then with the -member's \fIpublic name\fR which is obtained by removing the common member -name decorations, such as leading and trailing underscores, the \fBm_\fR -prefix, etc\. The ODB compiler also includes a number of built-in expressions -for commonly used accessor names, such as \fBget_foo\fR, \fBgetFoo\fR, -\fBgetfoo\fR, and just \fBfoo\fR\. The built-in expressions are tried last\. - -As an example, the following expression transforms data members with public -names in the form \fBfoo\fR to accessor names in the form \fBGetFoo\fR: - -\fB/(\.+)/Get\eu$1/\fR - -See also the REGEX AND SHELL QUOTING section below\. -.IP "\fB--accessor-regex-trace\fR" -Trace the process of applying regular expressions specified with the -\fB--accessor-regex\fR option\. Use this option to find out why your regular -expressions don't do what you expected them to do\. -.IP "\fB--modifier-regex\fR \fIregex\fR" -Add \fIregex\fR to the list of regular expressions used to transform data -member names to function names when searching for a suitable modifier -function\. The argument to this option is a Perl-like regular expression in -the form \fB/\fR\fIpattern\fR\fB/\fR\fIreplacement\fR\fB/\fR\fR\. Any -character can be used as a delimiter instead of '\fB/\fR' and the delimiter -can be escaped inside \fIpattern\fR and \fIreplacement\fR with a backslash -(\fB\e\fR)\. You can specify multiple regular expressions by repeating this -option\. - -All the regular expressions are tried in the order specified and the first -expression that produces a suitable modifier function is used\. Each -expression is tried twice: first with the actual member name and then with the -member's \fIpublic name\fR which is obtained by removing the common member -name decorations, such as leading and trailing underscores, the \fBm_\fR -prefix, etc\. The ODB compiler also includes a number of built-in expressions -for commonly used modifier names, such as \fBset_foo\fR, \fBsetFoo\fR, -\fBsetfoo\fR, and just \fBfoo\fR\. The built-in expressions are tried last\. - -As an example, the following expression transforms data members with public -names in the form \fBfoo\fR to modifier names in the form \fBSetFoo\fR: - -\fB/(\.+)/Set\eu$1/\fR - -See also the REGEX AND SHELL QUOTING section below\. -.IP "\fB--modifier-regex-trace\fR" -Trace the process of applying regular expressions specified with the -\fB--modifier-regex\fR option\. Use this option to find out why your regular -expressions don't do what you expected them to do\. -.IP "\fB--include-with-brackets\fR" -Use angle brackets (<>) instead of quotes ("") in the generated \fB#include\fR -directives\. -.IP "\fB--include-prefix\fR \fIprefix\fR" -Add \fIprefix\fR to the generated \fB#include\fR directive paths\. -.IP "\fB--include-regex\fR \fIregex\fR" -Add \fIregex\fR to the list of regular expressions used to transform generated -\fB#include\fR directive paths\. The argument to this option is a Perl-like -regular expression in the form -\fB/\fR\fIpattern\fR\fB/\fR\fIreplacement\fR\fB/\fR\fR\. Any character can be -used as a delimiter instead of '\fB/\fR' and the delimiter can be escaped -inside \fIpattern\fR and \fIreplacement\fR with a backslash (\fB\e\fR)\. You -can specify multiple regular expressions by repeating this option\. All the -regular expressions are tried in the order specified and the first expression -that matches is used\. - -As an example, the following expression transforms include paths in the form -\fBfoo/bar-odb\.h\fR to paths in the form \fBfoo/generated/bar-odb\.h\fR: - -\fB%foo/(\.+)-odb\.h%foo/generated/$1-odb\.h%\fR - -See also the REGEX AND SHELL QUOTING section below\. -.IP "\fB--include-regex-trace\fR" -Trace the process of applying regular expressions specified with the -\fB--include-regex\fR option\. Use this option to find out why your regular -expressions don't do what you expected them to do\. -.IP "\fB--guard-prefix\fR \fIprefix\fR" -Add \fIprefix\fR to the generated header inclusion guards\. The prefix is -transformed to upper case and characters that are illegal in a preprocessor -macro name are replaced with underscores\. -.IP "\fB--show-sloc\fR" -Print the number of generated physical source lines of code (SLOC)\. -.IP "\fB--sloc-limit\fR \fInum\fR" -Check that the number of generated physical source lines of code (SLOC) does -not exceed \fInum\fR\. -.IP "\fB--options-file\fR \fIfile\fR" -Read additional options from \fIfile\fR\. Each option should appear on a -separate line optionally followed by space or equal sign (\fB=\fR) and an -option value\. Empty lines and lines starting with \fB#\fR are ignored\. -Option values can be enclosed in double (\fB"\fR) or single (\fB'\fR) quotes -to preserve leading and trailing whitespaces as well as to specify empty -values\. If the value itself contains trailing or leading quotes, enclose it -with an extra pair of quotes, for example \fB'"x"'\fR\. Non-leading and -non-trailing quotes are interpreted as being part of the option value\. - -The semantics of providing options in a file is equivalent to providing the -same set of options in the same order on the command line at the point where -the \fB--options-file\fR option is specified except that the shell escaping -and quoting is not required\. Repeat this option to specify more than one -options file\. -.IP "\fB-x\fR \fIoption\fR" -Pass \fIoption\fR to the underlying C++ compiler (\fBg++\fR)\. The -\fIoption\fR value that doesn't start with '\fB-\fR' is considered the -\fBg++\fR executable name\. -.IP "\fB-v\fR" -Print the commands executed to run the stages of compilation\. -.IP "\fB--trace\fR" -Trace the compilation process\. -.IP "\fB--mysql-engine\fR \fIengine\fR" -Use \fIengine\fR instead of the default \fBInnoDB\fR in the generated database -schema file\. For more information on the storage engine options see the MySQL -documentation\. If you would like to use the database-default engine, pass -\fBdefault\fR as the value for this option\. -.IP "\fB--sqlite-override-null\fR" -Make all columns in the generated database schema allow \fBNULL\fR values\. -This is primarily useful in schema migration since SQLite does not support -dropping of columns\. By making all columns \fBNULL\fR we can later "delete" -them by setting their values to \fBNULL\fR\. Note that this option overrides -even the \fBnot_null\fR pragma\. -.IP "\fB--sqlite-lax-auto-id\fR" -Do not force monotonically increasing automatically-assigned object ids\. In -this mode the generated database schema omits the \fBAUTOINCREMENT\fR keyword -which results in faster object persistence but may lead to -automatically-assigned ids not being in a strictly ascending order\. Refer to -the SQLite documentation for details\. -.IP "\fB--pgsql-server-version\fR \fIver\fR" -Specify the minimum PostgreSQL server version with which the generated C++ -code and schema will be used\. This information is used to enable -version-specific optimizations and workarounds in the generated C++ code and -schema\. The version must be in the \fImajor\fR\fB\.\fR\fIminor\fR\fR form, -for example, \fB9\.1\fR\. If this option is not specified, then \fB7\.4\fR or -later is assumed\. -.IP "\fB--oracle-client-version\fR \fIver\fR" -Specify the minimum Oracle client library (OCI) version with which the -generated C++ code will be linked\. This information is used to enable -version-specific optimizations and workarounds in the generated C++ code\. The -version must be in the \fImajor\fR\fB\.\fR\fIminor\fR\fR form, for example, -\fB11\.2\fR\. If this option is not specified, then \fB10\.1\fR or later is -assumed\. -.IP "\fB--oracle-warn-truncation\fR" -Warn about SQL names that are longer than 30 characters and are therefore -truncated\. Note that during database schema generation -(\fB--generate-schema\fR) ODB detects when such truncations lead to name -conflicts and issues diagnostics even without this option specified\. -.IP "\fB--mssql-server-version\fR \fIver\fR" -Specify the minimum SQL Server server version with which the generated C++ -code and schema will be used\. This information is used to enable -version-specific optimizations and workarounds in the generated C++ code and -schema\. The version must be in the \fImajor\fR\fB\.\fR\fIminor\fR\fR form, -for example, \fB9\.0\fR (SQL Server 2005), \fB10\.5\fR (2008R2), or -\fB11\.0\fR (2012)\. If this option is not specified, then \fB10\.0\fR (SQL -Server 2008) or later is assumed\. -.IP "\fB--mssql-short-limit\fR \fIsize\fR" -Specify the short data size limit\. If a character, national character, or -binary data type has a maximum length (in bytes) less than or equal to this -limit, then it is treated as \fIshort data\fR, otherwise it is \fIlong -data\fR\. For short data ODB pre-allocates an intermediate buffer of the -maximum size and binds it directly to a parameter or result column\. This way -the underlying API (ODBC) can read/write directly from/to this buffer\. In the -case of long data, the data is read/written in chunks using the -\fBSQLGetData()\fR/\fBSQLPutData()\fR ODBC functions\. While the long data -approach reduces the amount of memory used by the application, it may require -greater CPU resources\. The default short data limit is 1024 bytes\. When -setting a custom short data limit, make sure that it is sufficiently large so -that no object id in the application is treated as long data\. -.\" -.\" SQL NAME TRANSFORMATIONS -.\" -.SH SQL NAME TRANSFORMATIONS -The ODB compiler provides a number of mechanisms for transforming -automatically-derived SQL names, such as tables, columns, etc., -to match a specific naming convention. At the higher level, we can -add a prefix to global names (tables and, for some databases, -indexes and/or foreign keys) with the -.B --table-prefix -option. Similarly, we can specify custom suffixes for automatically-derived -index -.RB ( --index-suffix ; -default is -.BR _i ), -foreign key -.RB ( --fkey-suffix ; -default is -.BR _fk ), -and sequence -.RB ( --sequence-suffix ; -default is -.BR _seq ) -names. Finally, we can also convert all the names to upper or lower -case with the -.B --sql-name-case -option (valid values are -.B upper -and -.BR lower ). - -At the lower level we can specify a set of regular expressions to -implement arbitrary transformations of the automatically-derived SQL -names. If we want a particular regular expression only to apply to -a specific name, for example, table or column, then we use one of the -.B --\fIkind\fB-regex -options, where -.I kind -can be -.BR table , -.BR column , -.BR index , -.BR fkey , -.BR sequence , -or -.BR statement . -On the other hand, if we want our regular expressions to apply to all SQL -names, then we use the -.B --sql-name-regex -option. - -The interaction between the higher and lower level transformations -is as follows. Prefixes and suffixes are added first. Then the -regular expression transformations are applied. Finally, if requested, -the name is converted to upper or lower case. Note also that all of -these transformations except for -.B --table-prefix -only apply to automatically-derived names. In other words, if a table, -column, etc., name was explicitly specified with a pragma, then it -is used as is, without applying any (except for the table prefix) -transformations. - -The value for the -.B --*-regex -options is a Perl-like regular expression in the form -.BI / pattern / replacement /\fR. -Any character can be used as a delimiter instead of -.B / -and the delimiter can be escaped inside -.I pattern -and -.I replacement -with a backslash -.RB ( \e ). -You can also specify multiple regular expressions by repeating these -options. - -All the regular expressions are tried in the order specified with the -name-specific expressions (for example, -.BR --table-regex) -tried first followed by the generic expressions -.RB ( --sql-name-regex ). -The first expression that matches is used. - -As an example, consider a regular expression that transforms a class -name in the form -.B CFoo -to a table name in the form -.BR FOO: - -.B --table-regex '/C(.+)/\eU$1/' - -As a more interesting example, consider the transformation of class -names that follow the upper camel case convention (for example, -.BR FooBar ) -to table names that follow the underscore-separated, all upper case -convention (for example, -.BR FOO_BAR ). -For this case we have to use separate expressions to handle one-word, -two-word, etc., names: - -.B --table-regex '/([A-z][a-z]+)/\eU$1/' - -.B --table-regex '/([A-z][a-z]+)([A-z][a-z]+)/\eU$1_$2/' - -See also the REGEX AND SHELL QUOTING section below. -.\" -.\" REGEX AND SHELL QUOTING -.\" -.SH REGEX AND SHELL QUOTING -When entering a regular expression argument in the shell command line -it is often necessary to use quoting (enclosing the argument in " " -or ' ') in order to prevent the shell from interpreting certain -characters, for example, spaces as argument separators and $ as -variable expansions. - -Unfortunately it is hard to achieve this in a manner that is portable -across POSIX shells, such as those found on GNU/Linux and UNIX, and -Windows shell. For example, if you use " " for quoting you will get -a wrong result with POSIX shells if your expression contains $. The -standard way of dealing with this on POSIX systems is to use ' ' -instead. Unfortunately, Windows shell does not remove ' ' from -arguments when they are passed to applications. As a result you may -have to use ' ' for POSIX and " " for Windows ($ is not treated as -a special character on Windows). - -Alternatively, you can save regular expression options into a file, -one option per line, and use this file with the -.B --options-file -option. With this approach you don't need to worry about shell quoting. -.\" -.\" DIAGNOSTICS -.\" -.SH DIAGNOSTICS -If the input file is not valid C++, -.B odb -will issue diagnostic messages to STDERR and exit with non-zero exit code. -.\" -.\" BUGS -.\" -.SH BUGS -Send bug reports to the odb-users@codesynthesis.com mailing list. -.\" -.\" COPYRIGHT -.\" -.SH COPYRIGHT -Copyright (c) 2009-2023 Code Synthesis Tools CC. - -Permission is granted to copy, distribute and/or modify this -document under the terms of the GNU Free Documentation License, -version 1.2; with no Invariant Sections, no Front-Cover Texts and -no Back-Cover Texts. Copy of the license can be obtained from -http://www.codesynthesis.com/licenses/fdl-1.3.txt diff --git a/doc/pregenerated/odb.xhtml b/doc/pregenerated/odb.xhtml deleted file mode 100644 index 0a9785c..0000000 --- a/doc/pregenerated/odb.xhtml +++ /dev/null @@ -1,978 +0,0 @@ - - - - - ODB 2.4.0 Compiler Command Line Manual - - - - - - - - - - - -
-
- -

NAME

- -

odb - object-relational mapping (ORM) compiler for C++

- -

SYNOPSIS

- -
-
odb [options] file [file...]
-
- -

DESCRIPTION

- -

Given a set of C++ classes in a header file, odb - generates C++ code that allows you to persist, query, and update objects - of these classes in a relational database (RDBMS). The relational - database that the generated code should target is specified with the - required --database option (see below).

- -

For an input file in the form name.hxx (other - file extensions can be used instead of .hxx), - in the single-database mode (the default), the generated C++ files - by default have the following names: - name-odb.hxx (header file), - name-odb.ixx (inline file), and - name-odb.cxx (source file). - - Additionally, if the --generate-schema option is - specified and the sql schema format is requested (see - --schema-format), the name.sql - database schema file is generated. If the separate - schema format is requested, the database creation code is generated - into the separate name-schema.cxx file.

- -

In the multi-database mode (see the --multi-database - option below), the generated files corresponding to the - common database have the same names as in the - single-database mode. For other databases, the file names include - the database name: - name-odb-db.hxx, - name-odb-db.ixx, - name-odb-db.cxx, - name-db.sql, and - name-schema-db.cxx - (where db is the database name).

- -

OPTIONS

-
-
--help
-
Print usage information and exit.
- -
--version
-
Print version and exit.
- -
-I dir
-
Add dir to the beginning of the list of - directories to be searched for included header files.
- -
-D name[=def]
-
Define macro name with definition - def. If definition is omitted, define - name to be 1.
- -
-U name
-
Cancel any previous definitions of macro name, - either built-in or provided with the -D option.
- -
--database|-d db
-
Generate code for the db database. Valid values - are mssql, mysql, - oracle, pgsql, - sqlite, and common (multi-database - mode only).
- -
--multi-database|-m type
-
Enable multi-database support and specify its type. Valid values for - this option are static and - dynamic. - -

In the multi-database mode, options that determine the kind (for - example, --schema-format), names (for example, - --odb-file-suffix), or content (for example, prologue - and epilogue options) of the output files can be prefixed with the - database name followed by a colon, for example, - mysql:value. This restricts the value of such an - option to only apply to generated files corresponding to this - database.

- -
--default-database db
-
When static multi-database support is used, specify the database that - should be made the default. When dynamic multi-database support is used, - common is always made the default database.
- -
--generate-query|-q
-
Generate query support code. Without this support you cannot use views - and can only load objects via their ids.
- -
--generate-prepared
-
Generate prepared query execution support code.
- -
--omit-unprepared
-
Omit un-prepared (once-off) query execution support code.
- -
--generate-session|-e
-
Generate session support code. With this option session support will - be enabled by default for all the persistent classes except those for - which it was explicitly disabled using the db session - pragma.
- -
--generate-schema|-s
-
Generate the database schema. The database schema contains SQL - statements that create database tables necessary to store persistent - classes defined in the file being compiled. Note that by applying this - schema, all the existing information stored in such tables will be lost. - -

Depending on the database being used (--database - option), the schema is generated either as a standalone SQL file or - embedded into the generated C++ code. By default the SQL file is generated - for the MySQL, PostgreSQL, Oracle, and Microsoft SQL Server databases and - the schema is embedded into the C++ code for the SQLite database. Use the - --schema-format option to alter the default schema - format.

- -

If database schema evolution support is enabled (that is, the object - model version is specified), then this option also triggers the generation - of database schema migration statements, again either as standalong SQL - files or embedded into the generated C++ code. You can suppress the - generation of schema migration statements by specifying the - --suppress-migration option.

- -
--generate-schema-only
-
Generate only the database schema. Note that this option is only valid - when generating schema as a standalone SQL file (see - --schema-format for details).
- -
--suppress-migration
-
Suppress the generation of database schema migration statements.
- -
--suppress-schema-version
-
Suppress the generation of schema version table. If you specify this - option then you are also expected to manually specify the database schema - version and migration state at runtime using the - odb::database::schema_version() function.
- -
--schema-version-table name
-
Specify the alternative schema version table name instead of the - default schema_version. If you specify this option - then you are also expected to manually specify the schema version table - name at runtime using the - odb::database::schema_version_table() function. The - table name can be qualified.
- -
--schema-format format
-
Generate the database schema in the specified format. Pass - sql as format to generate the - database schema as a standalone SQL file or pass - embedded to embed the schema into the generated C++ - code. The separate value is similar to - embedded except the schema creation code is generated - into a separate C++ file (name-schema.cxx by default). - This value is primarily useful if you want to place the schema creation - functionality into a separate program or library. Repeat this option to - generate the same database schema in multiple formats.
- -
--omit-drop
-
Omit DROP statements from the generated database - schema.
- -
--omit-create
-
Omit CREATE statements from the generated database - schema.
- -
--schema-name name
-
Use name as the database schema name. Schema names - are primarily used to distinguish between multiple embedded schemas in the - schema catalog. They are not to be confused with database schemas - (database namespaces) which are specified with the - --schema option. If this option is not specified, the - empty name, which is the default schema name, is used.
- -
--fkeys-deferrable-mode m
-
Use constraint checking mode m in foreign keys - generated for object relationships. Valid values for this option are - not_deferrable, immediate, and - deferred (default). MySQL and SQL Server do not - support deferrable foreign keys and for these databases such keys are - generated commented out. Other foreign keys generated by the ODB compiler - (such as the ones used to support containers and polymorphic hierarchies) - are always generated as not deferrable. - -

Note also that if you use either not_deferrable or - immediate mode, then the order in which you persist, - update, and erase objects within a transaction becomes important.

- -
--default-pointer ptr
-
Use ptr as the default pointer for persistent - objects and views. Objects and views that do not have a pointer assigned - with the db pointer pragma will use this pointer by - default. The value of this option can be '*' which - denotes the raw pointer and is the default, or qualified name of a smart - pointer class template, for example, std::shared_ptr. - In the latter case, the ODB compiler constructs the object or view pointer - by adding a single template argument of the object or view type to the - qualified name, for example - std::shared_ptr<object>. The ODB runtime uses - object and view pointers to return, and, in case of objects, pass and - cache dynamically allocated instances of object and view types. - -

Except for the raw pointer and the standard smart pointers defined in - the <memory> header file, you are expected to - include the definition of the default pointer at the beginning of the - generated header file. There are two common ways to achieve this: you can - either include the necessary header in the file being compiled or you can - use the --hxx-prologue option to add the necessary - #include directive to the generated code.

- -
--session-type type
-
Use type as the alternative session type instead - of the default odb::session. This option can be used - to specify a custom session implementation to be use by the persistent - classes. Note that you will also need to include the definition of the - custom session type into the generated header file. This is normally - achieved with the --hxx-prologue* options.
- -
--profile|-p name
-
Specify a profile that should be used during compilation. A profile is - an options file. The ODB compiler first looks for a database-specific - version with the name constructed by appending the - -database.options - suffix to name, where database is - the database name as specified with the --database - option. If this file is not found, then the ODB compiler looks for a - database-independant version with the name constructed by appending just - the .options suffix. - -

The profile options files are searched for in the same set of - directories as C++ headers included with the #include - <...> directive (built-in paths plus those specified with - the -I options). The options file is first searched - for in the directory itself and then in its odb/ - subdirectory.

- -

For the format of the options file refer to the - --options-file option below. You can repeat this - option to specify more than one profile.

- -
--at-once
-
Generate code for all the input files as well as for all the files - that they include at once. The result is a single set of source/schema - files that contain all the generated code. If more than one input file is - specified together with this option, then the - --input-name option must also be specified in order to - provide the base name for the output files. In this case, the directory - part of such a base name is used as the location of the combined file. - This can be important for the #include directive - resolution.
- -
--schema schema
-
Specify a database schema (database namespace) that should be assigned - to the persistent classes in the file being compiled. Database schemas are - not to be confused with database schema names (schema catalog names) which - are specified with the --schema-name option.
- -
--export-symbol symbol
-
Insert symbol in places where DLL export/import - control statements (__declspec(dllexport/dllimport)) - are necessary. See also the --extern-symbol option - below.
- -
--extern-symbol symbol
-
If symbol is defined, insert it in places where a - template instantiation must be declared extern. This - option is normally used together with --export-symbol - when both multi-database support and queries are enabled.
- -
--std version
-
Specify the C++ standard that should be used during compilation. Valid - values are c++98 (default), c++11, - c++14, c++17, and - c++20.
- -
--warn-hard-add
-
Warn about hard-added data members.
- -
--warn-hard-delete
-
Warn about hard-deleted data members and persistent classes.
- -
--warn-hard
-
Warn about both hard-added and hard-deleted data members and - persistent classes.
- -
--output-dir|-o dir
-
Write the generated files to dir instead of the - current directory.
- -
--input-name name
-
Use name instead of the input file to derive the - names of the generated files. If the --at-once option - is specified, then the directory part of name is used - as the location of the combined file. Refer to the - --at-once option for details.
- -
--changelog file
-
Read/write changelog from/to file instead of the - default changelog file. The default changelog file name is derived from - the input file name and it is placed into the same directory as the input - file. Note that the --output-dir option does not - affect the changelog file location. In other words, by default, the - changelog file is treated as another input rather than output even though - the ODB compiler may modify it. Use the --changelog-in - and --changelog-out options to specify different input - and output chaneglog files.
- -
--changelog-in file
-
Read changelog from file instead of the default - changelog file. If this option is specified, then you must also specify - the output chanegelog file with --changelog-out.
- -
--changelog-out file
-
Write changelog to file instead of the default - changelog file. If this option is specified, then you must also specify - the input chanegelog file with --changelog-in.
- -
--changelog-dir dir
-
Use dir instead of the input file directory as the - changelog file directory. This directory is also added to changelog files - specified with the --changelog, - --changelog-in, and --changelog-in - options unless they are absolute paths.
- -
--init-changelog
-
Force re-initialization of the changelog even if one exists (all the - existing change history will be lost). This option is primarily useful for - automated testing.
- -
--odb-file-suffix suffix
-
Use suffix to construct the names of the generated - C++ files. In the single-database mode the default value for this option - is -odb. In the multi-database mode it is - -odb for the files corresponding to the - common database and -odb-db - (where db is the database name) for other - databases.
- -
--sql-file-suffix suffix
-
Use suffix to construct the name of the generated - schema SQL file. In the single-database mode by default no suffix is used. - In the multi-database mode the default value for this option is - -db (where db is the - database name).
- -
--schema-file-suffix suffix
-
Use suffix to construct the name of the generated - schema C++ source file. In the single-database mode the default value for - this option is -schema. In the multi-database mode it - is -schema-db (where db is - the database name). See the --schema-format option for - details.
- -
--changelog-file-suffix sfx
-
Use sfx to construct the name of the changelog - file. In the single-database mode by default no suffix is used. In the - multi-database mode the default value for this option is - -db (where db is the - database name).
- -
--hxx-suffix suffix
-
Use suffix instead of the default - .hxx to construct the name of the generated C++ header - file.
- -
--ixx-suffix suffix
-
Use suffix instead of the default - .ixx to construct the name of the generated C++ inline - file.
- -
--cxx-suffix suffix
-
Use suffix instead of the default - .cxx to construct the name of the generated C++ source - file.
- -
--sql-suffix suffix
-
Use suffix instead of the default - .sql to construct the name of the generated database - schema file.
- -
--changelog-suffix suffix
-
Use suffix instead of the default - .xml to construct the name of the changelog file.
- -
--hxx-prologue text
-
Insert text at the beginning of the generated C++ - header file.
- -
--ixx-prologue text
-
Insert text at the beginning of the generated C++ - inline file.
- -
--cxx-prologue text
-
Insert text at the beginning of the generated C++ - source file.
- -
--schema-prologue text
-
Insert text at the beginning of the generated - schema C++ source file.
- -
--sql-prologue text
-
Insert text at the beginning of the generated - database schema file.
- -
--migration-prologue text
-
Insert text at the beginning of the generated - database migration file.
- -
--sql-interlude text
-
Insert text after all the DROP - and before any CREATE statements in the generated - database schema file.
- -
--hxx-epilogue text
-
Insert text at the end of the generated C++ header - file.
- -
--ixx-epilogue text
-
Insert text at the end of the generated C++ inline - file.
- -
--cxx-epilogue text
-
Insert text at the end of the generated C++ source - file.
- -
--schema-epilogue text
-
Insert text at the end of the generated schema C++ - source file.
- -
--sql-epilogue text
-
Insert text at the end of the generated database - schema file.
- -
--migration-epilogue text
-
Insert text at the end of the generated database - migration file.
- -
--hxx-prologue-file file
-
Insert the content of file at the beginning of the - generated C++ header file.
- -
--ixx-prologue-file file
-
Insert the content of file at the beginning of the - generated C++ inline file.
- -
--cxx-prologue-file file
-
Insert the content of file at the beginning of the - generated C++ source file.
- -
--schema-prologue-file file
-
Insert the content of file at the beginning of the - generated schema C++ source file.
- -
--sql-prologue-file file
-
Insert the content of file at the beginning of the - generated database schema file.
- -
--migration-prologue-file f
-
Insert the content of file f at the beginning of - the generated database migration file.
- -
--sql-interlude-file file
-
Insert the content of file after all the - DROP and before any CREATE - statements in the generated database schema file.
- -
--hxx-epilogue-file file
-
Insert the content of file at the end of the - generated C++ header file.
- -
--ixx-epilogue-file file
-
Insert the content of file at the end of the - generated C++ inline file.
- -
--cxx-epilogue-file file
-
Insert the content of file at the end of the - generated C++ source file.
- -
--schema-epilogue-file file
-
Insert the content of file at the end of the - generated schema C++ source file.
- -
--sql-epilogue-file file
-
Insert the content of file at the end of the - generated database schema file.
- -
--migration-epilogue-file f
-
Insert the content of file f at the end of the - generated database migration file.
- -
--odb-prologue text
-
Compile text before the input header file. This - option allows you to add additional declarations, such as custom traits - specializations, to the ODB compilation process.
- -
--odb-prologue-file file
-
Compile file contents before the input header - file. Prologue files are compiled after all the prologue text fragments - (--odb-prologue option).
- -
--odb-epilogue text
-
Compile text after the input header file. This - option allows you to add additional declarations, such as custom traits - specializations, to the ODB compilation process.
- -
--odb-epilogue-file file
-
Compile file contents after the input header file. - Epilogue files are compiled after all the epilogue text fragments - (--odb-epilogue option).
- -
--table-prefix prefix
-
Add prefix to table names and, for databases that - have global index and/or foreign key names, to those names as well. The - prefix is added to both names that were specified with the db - table and db index pragmas and those that - were automatically derived from class and data member names. If you - require a separator, such as an underscore, between the prefix and the - name, then you should include it into the prefix value.
- -
--index-suffix suffix
-
Use suffix instead of the default - _i to construct index names. The suffix is only added - to names that were automatically derived from data member names. If you - require a separator, such as an underscore, between the name and the - suffix, then you should include it into the suffix value.
- -
--fkey-suffix suffix
-
Use suffix instead of the default - _fk to construct foreign key names. If you require a - separator, such as an underscore, between the name and the suffix, then - you should include it into the suffix value.
- -
--sequence-suffix suffix
-
Use suffix instead of the default - _seq to construct sequence names. If you require a - separator, such as an underscore, between the name and the suffix, then - you should include it into the suffix value.
- -
--sql-name-case case
-
Convert all automatically-derived SQL names to upper or lower case. - Valid values for this option are upper and - lower.
- -
--table-regex regex
-
Add regex to the list of regular expressions that - is used to transform automatically-derived table names. See the SQL NAME - TRANSFORMATIONS section below for details.
- -
--column-regex regex
-
Add regex to the list of regular expressions that - is used to transform automatically-derived column names. See the SQL NAME - TRANSFORMATIONS section below for details.
- -
--index-regex regex
-
Add regex to the list of regular expressions that - is used to transform automatically-derived index names. See the SQL NAME - TRANSFORMATIONS section below for details.
- -
--fkey-regex regex
-
Add regex to the list of regular expressions that - is used to transform automatically-derived foreign key names. See the SQL - NAME TRANSFORMATIONS section below for details.
- -
--sequence-regex regex
-
Add regex to the list of regular expressions that - is used to transform automatically-derived sequence names. See the SQL - NAME TRANSFORMATIONS section below for details.
- -
--statement-regex regex
-
Add regex to the list of regular expressions that - is used to transform automatically-derived prepared statement names. See - the SQL NAME TRANSFORMATIONS section below for details.
- -
--sql-name-regex regex
-
Add regex to the list of regular expressions that - is used to transform all automatically-derived SQL names. See the SQL NAME - TRANSFORMATIONS section below for details.
- -
--sql-name-regex-trace
-
Trace the process of applying regular expressions specified with the - SQL name --*-regex options. Use this option to find - out why your regular expressions don't do what you expected them to - do.
- -
--accessor-regex regex
-
Add regex to the list of regular expressions used - to transform data member names to function names when searching for a - suitable accessor function. The argument to this option is a Perl-like - regular expression in the form - /pattern/replacement/. Any - character can be used as a delimiter instead of '/' - and the delimiter can be escaped inside pattern and - replacement with a backslash (\). - You can specify multiple regular expressions by repeating this option. - -

All the regular expressions are tried in the order specified and the - first expression that produces a suitable accessor function is used. Each - expression is tried twice: first with the actual member name and then with - the member's public name which is obtained by removing the common - member name decorations, such as leading and trailing underscores, the - m_ prefix, etc. The ODB compiler also includes a - number of built-in expressions for commonly used accessor names, such as - get_foo, getFoo, - getfoo, and just foo. The built-in - expressions are tried last.

- -

As an example, the following expression transforms data members with - public names in the form foo to accessor names in the - form GetFoo:

- -

/(.+)/Get\u$1/

- -

See also the REGEX AND SHELL QUOTING section below.

- -
--accessor-regex-trace
-
Trace the process of applying regular expressions specified with the - --accessor-regex option. Use this option to find out - why your regular expressions don't do what you expected them to do.
- -
--modifier-regex regex
-
Add regex to the list of regular expressions used - to transform data member names to function names when searching for a - suitable modifier function. The argument to this option is a Perl-like - regular expression in the form - /pattern/replacement/. Any - character can be used as a delimiter instead of '/' - and the delimiter can be escaped inside pattern and - replacement with a backslash (\). - You can specify multiple regular expressions by repeating this option. - -

All the regular expressions are tried in the order specified and the - first expression that produces a suitable modifier function is used. Each - expression is tried twice: first with the actual member name and then with - the member's public name which is obtained by removing the common - member name decorations, such as leading and trailing underscores, the - m_ prefix, etc. The ODB compiler also includes a - number of built-in expressions for commonly used modifier names, such as - set_foo, setFoo, - setfoo, and just foo. The built-in - expressions are tried last.

- -

As an example, the following expression transforms data members with - public names in the form foo to modifier names in the - form SetFoo:

- -

/(.+)/Set\u$1/

- -

See also the REGEX AND SHELL QUOTING section below.

- -
--modifier-regex-trace
-
Trace the process of applying regular expressions specified with the - --modifier-regex option. Use this option to find out - why your regular expressions don't do what you expected them to do.
- -
--include-with-brackets
-
Use angle brackets (<>) instead of quotes ("") in the generated - #include directives.
- -
--include-prefix prefix
-
Add prefix to the generated - #include directive paths.
- -
--include-regex regex
-
Add regex to the list of regular expressions used - to transform generated #include directive paths. The - argument to this option is a Perl-like regular expression in the form - /pattern/replacement/. Any - character can be used as a delimiter instead of '/' - and the delimiter can be escaped inside pattern and - replacement with a backslash (\). - You can specify multiple regular expressions by repeating this option. All - the regular expressions are tried in the order specified and the first - expression that matches is used. - -

As an example, the following expression transforms include paths in the - form foo/bar-odb.h to paths in the form - foo/generated/bar-odb.h:

- -

%foo/(.+)-odb.h%foo/generated/$1-odb.h%

- -

See also the REGEX AND SHELL QUOTING section below.

- -
--include-regex-trace
-
Trace the process of applying regular expressions specified with the - --include-regex option. Use this option to find out - why your regular expressions don't do what you expected them to do.
- -
--guard-prefix prefix
-
Add prefix to the generated header inclusion - guards. The prefix is transformed to upper case and characters that are - illegal in a preprocessor macro name are replaced with underscores.
- -
--show-sloc
-
Print the number of generated physical source lines of code - (SLOC).
- -
--sloc-limit num
-
Check that the number of generated physical source lines of code - (SLOC) does not exceed num.
- -
--options-file file
-
Read additional options from file. Each option - should appear on a separate line optionally followed by space or equal - sign (=) and an option value. Empty lines and lines - starting with # are ignored. Option values can be - enclosed in double (") or single - (') quotes to preserve leading and trailing - whitespaces as well as to specify empty values. If the value itself - contains trailing or leading quotes, enclose it with an extra pair of - quotes, for example '"x"'. Non-leading and - non-trailing quotes are interpreted as being part of the option value. - -

The semantics of providing options in a file is equivalent to providing - the same set of options in the same order on the command line at the point - where the --options-file option is specified except - that the shell escaping and quoting is not required. Repeat this option to - specify more than one options file.

- -
-x option
-
Pass option to the underlying C++ compiler - (g++). The option value that - doesn't start with '-' is considered the - g++ executable name.
- -
-v
-
Print the commands executed to run the stages of compilation.
- -
--trace
-
Trace the compilation process.
- -
--mysql-engine engine
-
Use engine instead of the default - InnoDB in the generated database schema file. For more - information on the storage engine options see the MySQL documentation. If - you would like to use the database-default engine, pass - default as the value for this option.
- -
--sqlite-override-null
-
Make all columns in the generated database schema allow - NULL values. This is primarily useful in schema - migration since SQLite does not support dropping of columns. By making all - columns NULL we can later "delete" them by setting - their values to NULL. Note that this option overrides - even the not_null pragma.
- -
--sqlite-lax-auto-id
-
Do not force monotonically increasing automatically-assigned object - ids. In this mode the generated database schema omits the - AUTOINCREMENT keyword which results in faster object - persistence but may lead to automatically-assigned ids not being in a - strictly ascending order. Refer to the SQLite documentation for - details.
- -
--pgsql-server-version ver
-
Specify the minimum PostgreSQL server version with which the generated - C++ code and schema will be used. This information is used to enable - version-specific optimizations and workarounds in the generated C++ code - and schema. The version must be in the - major.minor form, for example, - 9.1. If this option is not specified, then - 7.4 or later is assumed.
- -
--oracle-client-version ver
-
Specify the minimum Oracle client library (OCI) version with which the - generated C++ code will be linked. This information is used to enable - version-specific optimizations and workarounds in the generated C++ code. - The version must be in the major.minor - form, for example, 11.2. If this option is not - specified, then 10.1 or later is assumed.
- -
--oracle-warn-truncation
-
Warn about SQL names that are longer than 30 characters and are - therefore truncated. Note that during database schema generation - (--generate-schema) ODB detects when such truncations - lead to name conflicts and issues diagnostics even without this option - specified.
- -
--mssql-server-version ver
-
Specify the minimum SQL Server server version with which the generated - C++ code and schema will be used. This information is used to enable - version-specific optimizations and workarounds in the generated C++ code - and schema. The version must be in the - major.minor form, for example, - 9.0 (SQL Server 2005), 10.5 - (2008R2), or 11.0 (2012). If this option is not - specified, then 10.0 (SQL Server 2008) or later is - assumed.
- -
--mssql-short-limit size
-
Specify the short data size limit. If a character, national character, - or binary data type has a maximum length (in bytes) less than or equal to - this limit, then it is treated as short data, otherwise it is - long data. For short data ODB pre-allocates an intermediate buffer - of the maximum size and binds it directly to a parameter or result column. - This way the underlying API (ODBC) can read/write directly from/to this - buffer. In the case of long data, the data is read/written in chunks using - the SQLGetData()/SQLPutData() ODBC - functions. While the long data approach reduces the amount of memory used - by the application, it may require greater CPU resources. The default - short data limit is 1024 bytes. When setting a custom short data limit, - make sure that it is sufficiently large so that no object id in the - application is treated as long data.
-
- -

SQL NAME TRANSFORMATIONS

- -

The ODB compiler provides a number of mechanisms for transforming - automatically-derived SQL names, such as tables, columns, etc., - to match a specific naming convention. At the higher level, we can - add a prefix to global names (tables and, for some databases, - indexes and/or foreign keys) with the --table-prefix - option. Similarly, we can specify custom suffixes for - automatically-derived - index (--index-suffix; default is _i), - foreign key (--fkey-suffix; default is _fk), and - sequence (--sequence-suffix; default is _seq) - names. Finally, we can also convert all the names to upper or lower - case with the --sql-name-case option (valid values - are upper and lower).

- -

At the lower level we can specify a set of regular expressions to - implement arbitrary transformations of the automatically-derived SQL - names. If we want a particular regular expression only to apply to - a specific name, for example, table or column, then we use one of the - --kind-regex options, where - kind can be table, - column, index, - fkey, sequence, or - statement. On the other hand, if we want our - regular expressions to apply to all SQL names, then we use the - --sql-name-regex option.

- -

The interaction between the higher and lower level transformations - is as follows. Prefixes and suffixes are added first. Then the - regular expression transformations are applied. Finally, if requested, - the name is converted to upper or lower case. Note also that all of - these transformations except for --table-prefix - only apply to automatically-derived names. In other words, if a table, - column, etc., name was explicitly specified with a pragma, then it - is used as is, without applying any (except for the table prefix) - transformations.

- -

The value for the --*-regex options is a Perl-like - regular expression in the form - /pattern/replacement/. - Any character can be used as a delimiter instead of / - and the delimiter can be escaped inside pattern and - replacement with a backslash (\). - You can also specify multiple regular expressions by repeating these - options.

- -

All the regular expressions are tried in the order specified with the - name-specific expressions (for example, --table-regex) - tried first followed by the generic expressions - (--sql-name-regex). The first expression that - matches is used.

- -

As an example, consider a regular expression that transforms a class - name in the form CFoo to a table name in the - form FOO:

- -

--table-regex '/C(.+)/\U$1/'

- -

As a more interesting example, consider the transformation of class - names that follow the upper camel case convention (for example, - FooBar) to table names that follow the - underscore-separated, all upper case convention (for example, - FOO_BAR). For this case we have to use - separate expressions to handle one-word, two-word, etc., - names:

- -

--table-regex '/([A-z][a-z]+)/\U$1/'

-

--table-regex '/([A-z][a-z]+)([A-z][a-z]+)/\U$1_$2/'

- -

See also the REGEX AND SHELL QUOTING section below.

- -

REGEX AND SHELL QUOTING

- -

When entering a regular expression argument in the shell - command line it is often necessary to use quoting (enclosing - the argument in " " or - ' ') in order to prevent the shell - from interpreting certain characters, for example, spaces as - argument separators and $ as variable - expansions.

- -

Unfortunately it is hard to achieve this in a manner that is - portable across POSIX shells, such as those found on - GNU/Linux and UNIX, and Windows shell. For example, if you - use " " for quoting you will get a - wrong result with POSIX shells if your expression contains - $. The standard way of dealing with this - on POSIX systems is to use ' ' instead. - Unfortunately, Windows shell does not remove ' ' - from arguments when they are passed to applications. As a result you - may have to use ' ' for POSIX and - " " for Windows ($ is - not treated as a special character on Windows).

- -

Alternatively, you can save regular expression options into - a file, one option per line, and use this file with the - --options-file option. With this approach - you don't need to worry about shell quoting.

- -

DIAGNOSTICS

- -

If the input file is not valid C++, odb - will issue diagnostic messages to STDERR and exit with non-zero exit - code.

- -

BUGS

- -

Send bug reports to the - odb-users@codesynthesis.com mailing list.

- -
- -
- - -- cgit v1.1