Changeset: 84e2313812b5 for MonetDB URL: https://dev.monetdb.org/hg/MonetDB?cmd=changeset;node=84e2313812b5 Added Files: README documentation/old/HowToRelease.rst documentation/old/HowToStart.rst documentation/old/README.rst documentation/old/windowsbuild.rst documentation/source/cmake.rst Removed Files: HowToStart.rst README.rst buildtools/doc/HowToRelease.rst buildtools/doc/Makefile buildtools/doc/windowsbuild.rst Modified Files: cmake/Modules/FindSphinx.cmake documentation/index.rst Branch: default Log Message:
improve documentation, add cmake notes diffs (246 lines): diff --git a/README b/README new file mode 100644 --- /dev/null +++ b/README @@ -0,0 +1,22 @@ +The MonetDB Database System + +The MonetDB database is developed by the CWI database research group +(see https://www.monetdb.org/). + +Via the MonetDB project we have brought the MonetDB system in open source, +where it is accessible at https://www.monetdb.org/Downloads/ + +The MonetDB database system is a high-performance database kernel for +query-intensive applications. The MonetDB source can be found at our mercurial server (https://dev.monetdb.org/hg/MonetDB/). There is also a github clone (https://github.com/MonetDB/MonetDB) that is updated once a day. + +If you got a source distribution, please compile and install MonetDB first, +following the instructions in the "documentation" directory. + + +Copyright Notice + +This Source Code Form is subject to the terms of the Mozilla Public +License, v. 2.0. If a copy of the MPL was not distributed with this +file, You can obtain one at http://mozilla.org/MPL/2.0/. + +Copyright 1997 - July 2008 CWI, August 2008 - 2020 MonetDB B.V. diff --git a/buildtools/doc/Makefile b/buildtools/doc/Makefile deleted file mode 100644 --- a/buildtools/doc/Makefile +++ /dev/null @@ -1,13 +0,0 @@ -all: HowToRelease.html windowsbuild.html HowToRelease.pdf windowsbuild.pdf - -HowToRelease.html: HowToRelease.rst - rst2html HowToRelease.rst > HowToRelease.html - -windowsbuild.html: windowsbuild.rst - rst2html windowsbuild.rst > windowsbuild.html - -HowToRelease.pdf: HowToRelease.rst - rst2pdf HowToRelease.rst - -windowsbuild.pdf: windowsbuild.rst - rst2pdf windowsbuild.rst diff --git a/cmake/Modules/FindSphinx.cmake b/cmake/Modules/FindSphinx.cmake --- a/cmake/Modules/FindSphinx.cmake +++ b/cmake/Modules/FindSphinx.cmake @@ -1,14 +1,22 @@ +#[[ +# This Source Code Form is subject to the terms of the Mozilla Public +# License, v. 2.0. If a copy of the MPL was not distributed with this +# file, You can obtain one at http://mozilla.org/MPL/2.0/. +# +# Copyright 1997 - July 2008 CWI, August 2008 - 2020 MonetDB B.V. +#]] + find_program(SPHINX_EXECUTABLE NAMES sphinx-build - HINTS - $ENV{SPHINX_DIR} - PATH_SUFFIXES bin - DOC "Sphinx documentation generator" + HINTS + $ENV{SPHINX_DIR} + PATH_SUFFIXES bin + DOC "Sphinx documentation generator" ) include(FindPackageHandleStandardArgs) find_package_handle_standard_args(Sphinx DEFAULT_MSG - SPHINX_EXECUTABLE + SPHINX_EXECUTABLE ) mark_as_advanced(SPHINX_EXECUTABLE) diff --git a/documentation/index.rst b/documentation/index.rst --- a/documentation/index.rst +++ b/documentation/index.rst @@ -24,6 +24,7 @@ Welcome to MonetDB's documentation! source/input source/json source/manual_pages + source/cmake source/release Indices and tables diff --git a/buildtools/doc/HowToRelease.rst b/documentation/old/HowToRelease.rst rename from buildtools/doc/HowToRelease.rst rename to documentation/old/HowToRelease.rst diff --git a/HowToStart.rst b/documentation/old/HowToStart.rst rename from HowToStart.rst rename to documentation/old/HowToStart.rst diff --git a/README.rst b/documentation/old/README.rst rename from README.rst rename to documentation/old/README.rst diff --git a/buildtools/doc/windowsbuild.rst b/documentation/old/windowsbuild.rst rename from buildtools/doc/windowsbuild.rst rename to documentation/old/windowsbuild.rst diff --git a/documentation/source/cmake.rst b/documentation/source/cmake.rst new file mode 100644 --- /dev/null +++ b/documentation/source/cmake.rst @@ -0,0 +1,142 @@ +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, You can obtain one at http://mozilla.org/MPL/2.0/. +.. +.. Copyright 1997 - July 2008 CWI, August 2008 - 2020 MonetDB B.V. + +===== +CMake +===== + +``Introduction`` +================ + +``Packaging`` +============= +The source packages are located at https://www.monetdb.org/downloads/sources/Apr2019-SP1/ + +RPM +=== + +The source rpm's are located in https://www.monetdb.org/downloads/Fedora/source/ and are shared by all rpm based repositories. The debug packages are located in https://www.monetdb.org/downloads/Fedora/debug/ and https://www.monetdb.org/downloads/epel/debug/ The binary packages are located in https://www.monetdb.org/downloads/Fedora/ and https://www.monetdb.org/downloads/epel/ + +DEB +=== + +The source packages are located in https://www.monetdb.org/downloads/deb/dists/stretch/monetdb/source/ and the binary packages are located at https://www.monetdb.org/downloads/deb/ The source package setup for debian is totally different than for rpm's. + +MSI +=== + +The windows packages are located at https://www.monetdb.org/downloads/Windows/Apr2019-SP1/ + +### Mac OS X +The Mac OS X packages are downloaded from https://www.monetdb.org/downloads/MacOSX/ This repository contains a binary tarball and a pkg package. This last one is generated using the "MonetDB.pkgproj" file in the "MacOSX" directory in the source repository. The repository itself is only a download folder, there is no scripting needed to generate the repository itself. The third option to install monetdb on MacOS is to use homebrew. The relevant file is "https://github.com/MonetDB/homebrew-core/blob/master/Formula/monetdb.rb";, the repository is in the MonetDB github organization and is a clone of the homebrew repository. This file will need to be changes after swithing to cmake. The difficult part will likely be to keep this backwards compatible. + +``Releasing`` +============= + +``Versioning`` +============== + +``Source Code Management`` +========================== + +``Testing`` +=========== + +``CMake code structure`` +======================== + +Main file +========= + +CmakeLists.txt + +options +versions +includes +check features +install directory setup +build header files +add subdirectories +packaging +testing + +Options +======= + +In cmake, options can have the value ON or OFF. In the autotools system, many configure options where called "enable_xxxx" with the value true or false. To make the sure the cmake command "sounds logical" when read from the commandline, we choose to use short descriptions for the options. For example "enable_cintegration=true" becomes "-DCINTEGRATION=ON". + +The idea behind the defaults for the options also has changed from the autotools build system. Previously the idea was to limit the part of the code that was build in order to speed up the compilation. Parts of the code that were not required where only build when explicitly enabled. In the cmake build system this has been reversed. Now as much as possible is build, since compiling everything is now fast enough. In the cmake build system, every optional part is build, as long as the dependent libraries are detected. + +It is no longer possible to disable building major parts of the code, such as sql or mapi. And setting a certain option to off really means that you disable detecting the required libraries. For example, "-DODBC=OFF" means don't try detect the odbc development libraries. That implies that the odbc library will not be build. + +Most of the library detection is don in the "monetdb-findpackages" cmake file. We want to do this in such a way that we don't need a lot of logic. So for example, for the geom module library we only need to detect the geos library::: + + if(GEOM) + find_package(Geos) + endif() + +The find_packages function should define a "GEOS_FOUND" variable that is used throughout the rest of the cmake code. If you want to include a cmake file conditionally on the detection of a library, you should use that variable, for example in "geom/monetdb5/CMakeLists.txt" we use "if(GEOS_FOUND)". The only exception is in the monetdb_config.h file. Since the source code still uses legacy variables, usually "HAVE_xxx", we define them using this pattern::: + + #cmakedefine HAVE_GEOM @GEOS_FOUND@ + +This should give the correct result, because of the way "boolean" values, in combination with empty and non-existing variables work. The only situation where this might go wrong is when the variable explicitly has to have the value 1. This way, we cleanup as much of the legacy variables as possible from the build system. If the build system is setup correctly, the "HAVE_xxxx" variables should not be needed in most cases, because the code will only be build if the value = 1. + +Installing +========== + +To configure an install of a target, you have to define two things, where to install the file and the component that the file belongs to. And this has to be done for all the files that are part of the target. See the following example from the streams library to get an idea on how something would look::: + + install(TARGETS + stream + EXPORT streamTargets + RUNTIME + DESTINATION ${CMAKE_INSTALL_BINDIR} + COMPONENT stream + LIBRARY + DESTINATION ${CMAKE_INSTALL_LIBDIR} + COMPONENT stream + ARCHIVE + DESTINATION ${CMAKE_INSTALL_LIBDIR} + COMPONENT stream + PUBLIC_HEADER + COMPONENT streamdev + DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/monetdb + INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} + COMPONENT streamdev) + +When defining the destination, always use the "CMAKE\_INSTALL\_???DIR" variables, not the "CMAKE\_INSTALL\_FULL\_???DIR" ones. See https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html for the details, but the important part is that you should let CMake handle the "CMAKE\_INSTALL\_PREFIX". Only when the value is used inside the C code, or python scripts, you want to use the actual absolute paths. + +Unspecified +=========== + +- clients/odbc/samples + +``Legacy`` +========== + +Numpy detection +=============== + +Since the Python3::Numpy target is not available before version 3.14, we need an alternative. We use a NumPy detection function from a github project: https://raw.githubusercontent.com/fperazzi/davis-2017/master/cmake/FindNumPy.cmake This is MIT licensened, so we can include this in MonetDB. We change the python detection to detect python3, instead of python2. + +### Special monetdb_config.h for windows +Now there are two versions of the monetdb_config.h.in , one for windows and one for the rest of the supported OS-es. They should be merged. This is not trivial, because on windows the order in which certain header files are #include-d into the main one is very tricky. And both have a number of obsolete definitions that have to be removed. + +shp.h define conflicts +====================== + +We now disable some defines in sql/backends/monet5/vaults/shp/shp.h that were defined in monetdb_config.h because they conflict with defines in gdal library header files.:: + + /* these were previously defined in monetdb_config.h */ + #undef HAVE_DLFCN_H + #undef HAVE_FCNTL_H + #undef HAVE_ICONV + #undef HAVE_STRINGS_H + +kvm library +=========== + +The kvm library is only used on \*bsd. We already remove the header detection from cmakelists.txt: "find_path(HAVE_KVM_H "kvm.h")". _______________________________________________ checkin-list mailing list checkin-list@monetdb.org https://www.monetdb.org/mailman/listinfo/checkin-list
