Permalink
Browse files

io: documentation & cmake improvements

  • Loading branch information...
waht committed Dec 29, 2017
1 parent 293b064 commit 1ef4d9e0db6684468596205bcf6c2417e3d51bc3
Showing with 1,353 additions and 896 deletions.
  1. +2 −2 .travis.yml
  2. +1 −1 cmake/ElektraCache.cmake
  3. +71 −49 cmake/Modules/LibAddBinding.cmake
  4. +2 −2 cmake/Modules/LibAddHaskellPlugin.cmake
  5. +0 −24 cmake/Modules/LibAddMacros.cmake
  6. +7 −0 doc/AUTHORS.md
  7. +6 −9 doc/COMPILE.md
  8. +1 −1 doc/CONTRACT.ini
  9. +3 −1 doc/Doxyfile
  10. +62 −47 doc/tutorials/notifications.md
  11. +0 −1 scripts/configure-debian
  12. +1 −1 scripts/configure-debian-debug
  13. +1 −1 scripts/configure-debian-log
  14. +1 −0 scripts/configure-debian-musl
  15. +1 −1 scripts/configure-debian-optimizations
  16. +12 −21 src/bindings/CMakeLists.txt
  17. +18 −6 src/bindings/README.md
  18. +3 −1 src/bindings/cpp/CMakeLists.txt
  19. +6 −3 src/bindings/cpp/README.md
  20. +2 −2 src/bindings/cpp/benchmarks/CMakeLists.txt
  21. +2 −2 src/bindings/cpp/examples/CMakeLists.txt
  22. +1 −1 src/bindings/cpp/include/CMakeLists.txt
  23. +3 −3 src/bindings/cpp/tests/CMakeLists.txt
  24. +15 −9 src/bindings/gi/CMakeLists.txt
  25. +5 −5 src/bindings/gi/lua/CMakeLists.txt
  26. +6 −3 src/bindings/gi/lua/README.md
  27. +3 −3 src/bindings/gi/python/CMakeLists.txt
  28. +6 −3 src/bindings/gi/python/README.md
  29. +9 −8 src/bindings/glib/CMakeLists.txt
  30. +6 −3 src/bindings/glib/README.md
  31. +1 −1 src/bindings/glib/tests/CMakeLists.txt
  32. +25 −11 src/bindings/gsettings/CMakeLists.txt
  33. +6 −3 src/bindings/gsettings/README.md
  34. +8 −6 src/bindings/haskell/CMakeLists.txt
  35. +6 −3 src/bindings/haskell/README.md
  36. +2 −4 src/bindings/intercept/CMakeLists.txt
  37. +4 −2 src/bindings/intercept/env/CMakeLists.txt
  38. +2 −1 src/bindings/intercept/env/README.md
  39. +2 −2 src/bindings/intercept/env/benchmarks/CMakeLists.txt
  40. +2 −2 src/bindings/intercept/env/examples/CMakeLists.txt
  41. +1 −1 src/bindings/intercept/env/tests/CMakeLists.txt
  42. +4 −2 src/bindings/intercept/fs/CMakeLists.txt
  43. +2 −1 src/bindings/intercept/fs/README.md
  44. +2 −2 src/bindings/io/CMakeLists.txt
  45. +0 −12 src/bindings/io/README.md
  46. +12 −10 src/bindings/io/doc/CMakeLists.txt
  47. +9 −2 src/bindings/io/doc/README.md
  48. +1 −1 src/bindings/io/doc/elektra-io-doc.pc.in
  49. +302 −98 src/bindings/io/doc/io_doc.c
  50. +5 −0 src/bindings/io/doc/{io_doc.h → kdbio_doc.h}
  51. +17 −3 src/bindings/io/doc/testio_doc.c
  52. +6 −5 src/bindings/io/test/test.c
  53. +1 −0 src/bindings/io/test/test.h
  54. +11 −10 src/bindings/io/test/test_fd.c
  55. +11 −10 src/bindings/io/test/test_idle.c
  56. +5 −4 src/bindings/io/test/test_mix.c
  57. +11 −10 src/bindings/io/test/test_timer.c
  58. +2 −1 src/bindings/io/test/test_utils.c
  59. +20 −18 src/bindings/io/uv/CMakeLists.txt
  60. +8 −8 src/bindings/io/uv/README.md
  61. +1 −1 src/bindings/io/uv/elektra-io-uv.pc.in
  62. +4 −4 src/bindings/io/uv/example/CMakeLists.txt
  63. +24 −18 src/bindings/io/uv/example/exampleio_uv.c
  64. +65 −67 src/bindings/io/uv/io_uv.c
  65. +5 −0 src/bindings/io/uv/kdbio_uv.h
  66. +4 −4 src/bindings/io/uv/testio_uv.c
  67. +6 −4 src/bindings/jna/CMakeLists.txt
  68. +8 −3 src/bindings/jna/README.md
  69. +7 −9 src/bindings/swig/CMakeLists.txt
  70. +5 −5 src/bindings/swig/lua/CMakeLists.txt
  71. +6 −3 src/bindings/swig/lua/README.md
  72. +1 −1 src/bindings/swig/lua/tests/CMakeLists.txt
  73. +10 −9 src/bindings/swig/python/CMakeLists.txt
  74. +6 −3 src/bindings/swig/python/README.md
  75. +1 −1 src/bindings/swig/python/tests/CMakeLists.txt
  76. +9 −9 src/bindings/swig/python2/CMakeLists.txt
  77. +6 −3 src/bindings/swig/python2/README.md
  78. +1 −1 src/bindings/swig/python2/tests/CMakeLists.txt
  79. +15 −15 src/bindings/swig/ruby/CMakeLists.txt
  80. +6 −3 src/bindings/swig/ruby/README.md
  81. +251 −183 src/include/kdbio.h
  82. +44 −38 src/include/kdbioprivate.h
  83. +48 −0 src/include/kdbiotest.h
  84. +1 −1 src/libs/io/elektra-io.pc.in
  85. +74 −64 src/libs/io/io.c
  86. +1 −1 src/plugins/doc/doc.h
View
@@ -127,7 +127,7 @@ before_script:
if [[ "$TRAVIS_OS_NAME" == "linux" && "$CC" == "clang" || "$TRAVIS_OS_NAME" == "osx" && "${CC:0:3}" == "gcc" ]]; then
CMAKE_OPT+=("-DCOMMON_FLAGS=-Werror")
fi
- if [[ $HASKELL == ON ]]; then bindings="STABLE;haskell"; fi
- if [[ $HASKELL == ON ]]; then bindings="haskell"; fi
- |
if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
python2_ver=$(python2 -c 'import sys; print(".".join(map(str, sys.version_info[:2])))') && \
@@ -143,7 +143,7 @@ before_script:
-GNinja
-DBUILD_STATIC=OFF
-DPLUGINS="${plugins:-ALL;-jni}"
-DBINDINGS="${bindings:-STABLE}"
-DBINDINGS="${bindings}"
-DENABLE_DEBUG=ON
-DTOOLS=ALL
-DINSTALL_SYSTEM_FILES=OFF
View
@@ -37,7 +37,7 @@ set (ADDED_DIRECTORIES "" CACHE STRING ${PLUGINS_DOC} FORCE)
set (BINDINGS_DOC "Which bindings should be added? ALL for all available, DEFAULT for minimal set, see doc/COMPILE.md.")
set(BINDINGS "DEFAULT" CACHE STRING ${BINDINGS_DOC})
set(BINDINGS "MAINTAINED;-EXPERIMENTAL;-DEPRECATED" CACHE STRING ${BINDINGS_DOC})
set (INFO_BINDINGS_DOC "only for informational purposes. Modify BINDINGS to change the list.")
set (ADDED_BINDINGS_DOC "List of bindings already added, ${INFO_BINDINGS_DOC}")
@@ -1,11 +1,16 @@
include(LibAddMacros)
# - adds a binding if it is included in BINDINGS and not exluded.
# - Adds a binding if it is included in BINDINGS and not exluded by name or
# category (infos/status or infos/provides from it's README.md).
#
# If the binding is exluded the reason is printed along with the binding name.
# This is function is intended to be used in a CMakeLists.txt in the directory
# above or within the actual binding directory.
#
# try_add_binding (BINDING_NAME OUTVARIABLE)
# This is function can be used anywhere since the base directory is fixed to
# the bindings source directory. However if the binding uses subdirectories
# (like swig, gi or io) you need to supply the correct SUBDIRECTORY option
# (see examples).
#
# check_binding_included (BINDING_NAME OUTVARIABLE)
#
# BINDING_NAME:
# name of the binding
@@ -20,46 +25,52 @@ include(LibAddMacros)
# Default for SUBDIRECTORY is BINDING_NAME
#
# Example:
# try_add_binding ("swig_python" IS_INCLUDED SUBDIRECTORY "python")
# check_binding_included ("swig_python" IS_INCLUDED SUBDIRECTORY "swig/python")
# if (IS_INCLUDED)
# add_subdirectory (python)
# endif ()
#
function (try_add_binding BINDING_NAME OUTVARIABLE)
function (check_binding_included BINDING_NAME OUTVARIABLE)
cmake_parse_arguments (ARG
"SILENT" # optional keywords
"" # one value keywords
"" # multi value keywords
${ARGN}
)
check_item_is_excluded (IS_EXCLUDED BINDINGS ${BINDING_NAME} SUBDIRECTORY ${BINDING_NAME} ${ARGN})
check_item_is_excluded (
IS_EXCLUDED
BINDINGS
${BINDING_NAME}
SUBDIRECTORY ${BINDING_NAME}
BASEDIRECTORY "${CMAKE_SOURCE_DIR}/src/bindings"
ENABLE_PROVIDES
${ARGN}
)
if (IS_EXCLUDED)
if (ARG_SILENT)
# make sure that the exclusion message is not printed
set (IS_EXCLUDED "silent")
endif ()
remove_binding (${BINDING_NAME} ${IS_EXCLUDED} REMOVE_NOT_NECESSARY)
set (${OUTVARIABLE} "" PARENT_SCOPE)
exclude_binding (${BINDING_NAME} ${IS_EXCLUDED})
set (${OUTVARIABLE} "NO" PARENT_SCOPE)
else ()
add_binding_manual (${BINDING_NAME})
set (${OUTVARIABLE} "YES" PARENT_SCOPE)
endif ()
endfunction (try_add_binding)
endfunction (check_binding_included)
# - add a binding to list of bindings that will be built.
# Can be used if a binding depends on another binding and you want to
# silently include it rather than display an error.
#- Add a binding to list of bindings that will be built and print corresponding
# message.
#
# add_binding_manual (BINDING_NAME)
# add_binding (BINDING_NAME)
#
# BINDING_NAME:
# name of the binding
# BINDING_NAME:
# name of the binding
#
# Example:
# add_binding_manual ("anynameyouwant")
# example:
# add_binding ("anynameyouwant")
#
function (add_binding_manual BINDING_NAME)
function (add_binding BINDING_NAME)
if (ADDED_BINDINGS)
set (TMP "${ADDED_BINDINGS};${BINDING_NAME}")
list (SORT TMP)
@@ -68,43 +79,54 @@ function (add_binding_manual BINDING_NAME)
else ()
set (ADDED_BINDINGS "${BINDING_NAME}" CACHE STRING "${ADDED_BINDINGS_DOC}" FORCE)
endif ()
endfunction (add_binding_manual)
# - check if a binding is included in the BINDINGS list given by the user.
# If it is included it is not guaranteed that the binding will be built
# (dependencies can be missing, etc.)
# This is function can be used anywhere since the base directory is fixed to
# the bindings directory. However if the binding uses subdirectories
# (like swig, gi or io) you need to supply the correct SUBDIRECTORY option
# (see examples).
message (STATUS "Include Binding ${BINDING_NAME}")
endfunction (add_binding)
#- Remove a binding from the global cache
#
# check_binding_included (BINDING_NAME OUTVARIABLE)
# exclude_binding (name reason)
#
# BINDING_NAME:
# name of the binding
# name
# binding name
#
# OUTVARIABLE:
# variable that is set to true if binding was added
# reason
# reason for exclusion
#
# Additional options are passed to check_item_is_excluded ().
# Default for SUBDIRECTORY is BINDING_NAME
# REMOVE
# (optional) remove already added with add_binding.
# Consistency check: If not given it is made sure that the binding is not on
# the list.
#
# Example:
# check_binding_included ("swig_python" IS_INCLUDED SUBDIRECTORY "swig/python")
# if (IS_INCLUDED)
# add_subdirectory (python)
# endif ()
# example:
# exclude_binding (fstab "mntent is missing")
#
function (check_binding_included BINDING_NAME OUTVARIABLE)
check_item_is_excluded (IS_EXCLUDED BINDINGS ${BINDING_NAME} SUBDIRECTORY ${BINDING_NAME} BASEDIRECTORY "${CMAKE_SOURCE_DIR}/src/bindings" ${ARGN})
if (IS_EXCLUDED)
set (${OUTVARIABLE} "" PARENT_SCOPE)
function (exclude_binding name reason)
cmake_parse_arguments (ARG
"REMOVE" # optional keywords
"" # one value keywords
"" # multi value keywords
${ARGN}
)
if (NOT ${reason} STREQUAL "silent")
message (STATUS "Exclude Binding ${name} because ${reason}")
endif ()
if (ARG_REMOVE)
if (ADDED_BINDINGS)
set (TMP ${ADDED_BINDINGS})
list (REMOVE_ITEM TMP ${name})
set (ADDED_BINDINGS ${TMP} CACHE STRING ${ADDED_BINDINGS_DOC} FORCE)
endif ()
else ()
set (${OUTVARIABLE} "YES" PARENT_SCOPE)
list (FIND ADDED_BINDINGS "${name}" FOUND_NAME)
if (FOUND_NAME GREATER -1)
message (WARNING "Internal inconsistency: REMOVE_NOT_NECESSARY given but ${name} is present in bindings!")
endif ()
endif ()
endfunction (check_binding_included)
endfunction (exclude_binding)
# - check if a binding will be built.
# - Check if a binding will be built.
# Can only be used run after bindins have been processed (e.g. in
# ADDTESTING_PHASE of plugins)
# This is function can be used anywhere.
@@ -128,7 +150,7 @@ function (check_binding_was_added BINDING_NAME OUTVARIABLE)
if (FINDEX GREATER -1)
set (${OUTVARIABLE} "YES" PARENT_SCOPE)
else ()
set (${OUTVARIABLE} "" PARENT_SCOPE)
set (${OUTVARIABLE} "NO" PARENT_SCOPE)
endif ()
endfunction (check_binding_was_added)
@@ -171,7 +193,7 @@ function (check_item_is_excluded OUTVARIABLE LIST ITEM_NAME)
"" # multi value keywords
${ARGN}
)
set (${OUTVARIABLE} "" PARENT_SCOPE)
set (${OUTVARIABLE} "NO" PARENT_SCOPE)
list (FIND ${LIST} "-${ITEM_NAME}" FOUND_EXCLUDE_NAME)
if (FOUND_EXCLUDE_NAME GREATER -1)
@@ -30,7 +30,7 @@ macro (add_haskell_plugin target)
# set by find_program
if (HASKELL_FOUND)
check_binding_included ("haskell" BINDING_WAS_INCLUDED)
check_binding_included ("haskell" BINDING_WAS_INCLUDED SILENT)
if (BINDING_WAS_INCLUDED)
# needed for HsFFI.h
@@ -131,7 +131,7 @@ macro (add_haskell_plugin target)
remove_plugin (${target} "GHC_FFI_LIB not found")
endif (GHC_FFI_LIB)
endif (APPLE)
# configure include paths
configure_file (
"${CMAKE_CURRENT_SOURCE_DIR}/${target}.cabal.in"
@@ -278,30 +278,6 @@ macro (remove_plugin name reason)
endmacro (remove_plugin)
macro (remove_binding name reason)
cmake_parse_arguments (ARG
"REMOVE_NOT_NECESSARY" # optional keywords
"" # one value keywords
"" # multi value keywords
${ARGN}
)
if (NOT ${reason} STREQUAL "silent")
message (STATUS "Exclude Binding ${name} because ${reason}")
endif ()
if (NOT ARG_REMOVE_NOT_NECESSARY)
set (TMP ${ADDED_BINDINGS})
list (REMOVE_ITEM TMP ${name})
set (ADDED_BINDINGS ${TMP} CACHE STRING ${ADDED_BINDINGS_DOC} FORCE)
else ()
list (FIND ADDED_BINDINGS "${name}" FOUND_NAME)
if (FOUND_NAME GREATER -1)
message (WARNING "Internal inconsistency: REMOVE_NOT_NECESSARY given but ${name} is present in bindings!")
endif ()
endif ()
endmacro (remove_binding)
macro (remove_tool name reason)
set (TMP ${TOOLS})
message (STATUS "Exclude tool ${name} because ${reason}")
View
@@ -207,3 +207,10 @@ ruby bindings, ruby plugin, build server, Puppet module
- github user: [BernhardDenner](https://github.com/BernhardDenner)
- devel/test on: Ubuntu and Debian
## Thomas Wahringer
notification system, I/O bindings
- email: waht@libelektra.org
- github user: [waht](https://github.com/waht)
- devel/test on: Debian
View
@@ -305,10 +305,11 @@ To specify specific tools you can use, e.g.:
#### Bindings
Bindings are used in a similar way as `PLUGINS`.
For example, to build ALL bindings and exclude experimental bindings you can use:
Bindings are used in a like as `PLUGINS`.
For example, to build all maintainted bindings and exclude experimental bindings
you can use:
-DBINDINGS=ALL;-EXPERIMENTAL
-DBINDINGS=MAINTAINED;-EXPERIMENTAL
Note that the same languages are sometimes available over GI and SWIG.
In this case, the SWIG bindings are preferred.
@@ -332,12 +333,8 @@ To not add such APIs, but only `swig` bindings and `cpp`, you can use:
-DBINDINGS="SWIG;cpp"
Other available categories of bindings are:
- `DEFAULT` to build default bindings
- `STABLE` to build all stable bindings (without experimental and deprecated
ones)
- `DEPRECATED` can be used to exclude deprecated bindings
For a list of available bindings see
[binding's README.md](/src/bindings/README.md).
#### CMAKE_BUILD_TYPE
View
@@ -313,7 +313,7 @@ type = vector<int enum>
{"obsolete", -4000}, ; another plugin fulfils a similar functionality in a better way
{"discouraged", -32000}, ; only use the plugin if you really know what you are doing
status = implemented
usedby = plugin spec
usedby = plugin spec binding
description = Tags about how well-established and well-working a plugin is.
Different status can be combined.
View
@@ -769,6 +769,7 @@ INPUT = "@PROJECT_SOURCE_DIR@/src/libs" \
"@PROJECT_SOURCE_DIR@/src/include" \
"@PROJECT_SOURCE_DIR@/src/bindings/cpp/include" \
"@PROJECT_SOURCE_DIR@/src/bindings/jna/libelektra4j/src" \
"@PROJECT_SOURCE_DIR@/src/bindings/io/doc/io_doc.c" \
"@PROJECT_SOURCE_DIR@/src/plugins" \
"@PROJECT_SOURCE_DIR@/src/plugins/doc/doc.h" \
"@PROJECT_SOURCE_DIR@/doc" \
@@ -876,7 +877,8 @@ EXAMPLE_PATH = "@PROJECT_SOURCE_DIR@/examples" \
"@PROJECT_SOURCE_DIR@/tests/abi" \
"@PROJECT_SOURCE_DIR@/tests/ctest" \
"@PROJECT_SOURCE_DIR@/tests/cframework" \
"@PROJECT_SOURCE_DIR@/src/plugins/doc"
"@PROJECT_SOURCE_DIR@/src/plugins/doc" \
"@PROJECT_SOURCE_DIR@/src/bindings/io/doc"
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
Oops, something went wrong.

0 comments on commit 1ef4d9e

Please sign in to comment.