Merge branch 'master' into release

.gitignore

@@ -1,6 +1,5 @@
 *.o
 *.so
-/luastatus/luastatus
 /_gitignored/
 # CMake
 CMakeCache.txt
@@ -12,6 +11,4 @@ install_manifest.txt
 CTestTestfile.cmake
 build/
 # generated headers
-/config.h
-/version.h
-/probes.h
+*.generated.[ch]

CMakeLists.txt

@@ -44,14 +44,15 @@ else ()
             lua53 lua-5.3 lua5.3
             lua52 lua-5.2 lua5.2
             lua51 lua-5.1 lua5.1
-            luajit)
+            luajit
+            lua)
     endif ()
 endif ()
 
 function (luastatus_target_compile_with target var)
     target_include_directories (${target} SYSTEM PUBLIC
         ${${var}_INCLUDE_DIRS})
-    target_compile_definitions (${target} PUBLIC
+    target_compile_options (${target} PUBLIC
         ${${var}_CFLAGS_OTHER})
 endfunction ()
 
@@ -62,16 +63,19 @@ function (luastatus_target_build_with target var)
 endfunction ()
 
 #------------------------------------------------------------------------------
+include(GNUInstallDirs)
 
-set (BARLIBS_DIR "${CMAKE_INSTALL_PREFIX}/lib/luastatus/barlibs")
-set (PLUGINS_DIR "${CMAKE_INSTALL_PREFIX}/lib/luastatus/plugins")
+set (BARLIBS_DIR "${CMAKE_INSTALL_FULL_LIBDIR}/luastatus/barlibs")
+set (PLUGINS_DIR "${CMAKE_INSTALL_FULL_LIBDIR}/luastatus/plugins")
 
 function (luastatus_add_barlib_or_plugin destdir name)
     set (sources ${ARGV})
     list (REMOVE_AT sources 0 1)
     add_library ("${name}" MODULE ${sources})
     set_target_properties ("${name}" PROPERTIES PREFIX "")
-    install (TARGETS "${name}" DESTINATION "${destdir}")
+    if (destdir)
+        install (TARGETS "${name}" DESTINATION "${destdir}")
+    endif ()
 endfunction ()
 
 function (luastatus_add_barlib)
@@ -82,15 +86,24 @@ function (luastatus_add_plugin)
     luastatus_add_barlib_or_plugin ("${PLUGINS_DIR}" ${ARGV})
 endfunction ()
 
+function (luastatus_add_barlib_noinstall)
+    luastatus_add_barlib_or_plugin ("" ${ARGV})
+endfunction ()
+
+function (luastatus_add_plugin_noinstall)
+    luastatus_add_barlib_or_plugin ("" ${ARGV})
+endfunction ()
+
 #------------------------------------------------------------------------------
 
 option (BUILD_BARLIB_DWM "build barlibs/dwm" ON)
 option (BUILD_BARLIB_I3 "build barlibs/i3" ON)
+option (BUILD_BARLIB_LEMONBAR "build barlibs/lemonbar" ON)
 
 option (BUILD_PLUGIN_ALSA "build plugins/alsa" ON)
 option (BUILD_PLUGIN_FS "build plugins/fs" ON)
+option (BUILD_PLUGIN_INOTIFY "build plugins/inotify" ON)
 option (BUILD_PLUGIN_MPD "build plugins/mpd" ON)
-option (BUILD_PLUGIN_PIPE "build plugins/pipe" ON)
 option (BUILD_PLUGIN_TIMER "build plugins/timer" ON)
 option (BUILD_PLUGIN_XKB "build plugins/xkb" ON)
 option (BUILD_PLUGIN_XTITLE "build plugins/xtitle" ON)
@@ -99,6 +112,7 @@ option (BUILD_PLUGIN_XTITLE "build plugins/xtitle" ON)
 
 add_subdirectory (libls)
 add_subdirectory (luastatus)
+add_subdirectory (tests)
 
 if (BUILD_BARLIB_DWM)
     add_subdirectory (barlibs/dwm)
@@ -108,6 +122,10 @@ if (BUILD_BARLIB_I3)
     add_subdirectory (barlibs/i3)
 endif ()
 
+if (BUILD_BARLIB_LEMONBAR)
+    add_subdirectory (barlibs/lemonbar)
+endif ()
+
 if (BUILD_PLUGIN_ALSA)
     add_subdirectory (plugins/alsa)
 endif ()
@@ -116,12 +134,12 @@ if (BUILD_PLUGIN_FS)
     add_subdirectory (plugins/fs)
 endif ()
 
-if (BUILD_PLUGIN_MPD)
-    add_subdirectory (plugins/mpd)
+if (BUILD_PLUGIN_INOTIFY)
+    add_subdirectory (plugins/inotify)
 endif ()
 
-if (BUILD_PLUGIN_PIPE)
-    add_subdirectory (plugins/pipe)
+if (BUILD_PLUGIN_MPD)
+    add_subdirectory (plugins/mpd)
 endif ()
 
 if (BUILD_PLUGIN_TIMER)

DOCS/MIGRATION_GUIDE.md

@@ -0,0 +1,21 @@
+0.0.1 to 0.0.2
+===
+* `luastatus.spawn`, `luastatus.rc` and `luastatus.dollar` functions have been removed.
+   Use `os.execute` and/or `io.popen` instead — and please don’t forget to properly escape the arguments:
+    ````lua
+    function shell_escape(s)
+        return "'" .. s:gsub("'", "'\\''") .. "'"
+    end
+    ````
+
+* `pipe` plugin has been removed. Use the `timer` plugin and `io.open` instead:
+    ````lua
+    wdiget = {
+        plugin = 'timer',
+        cb = function()
+            for line in assert(io.open('your command', 'r')):lines() do
+                -- blah-blah-blah
+            end
+        end,
+    }
+    ````

DOCS/WRITING_BARLIB_OR_PLUGIN.md

@@ -0,0 +1,36 @@
+Thread-safety
+===
+Each non-thread-safe thing must be synchronized with other entities by means of
+the `map_get` function (see `DOCS/design/map_get.md`).
+
+Misc
+===
+Your plugin or barlib must not modify environment variables (this includes
+`unsetenv()`, `setenv()`, `putenv()`, and modifying `environ`).
+
+Your plugin or barlib can install signal handlers, but:
+
+  1. this must be done with `sigaction()`, and `sa_mask` field of
+  `struct sigaction` must include `SA_RESTART`.
+
+  2. the handler must not be `SIG_IGN`, as it gets inherited by child
+  processes;
+
+  3. you must add a taint with the name of the signal, e.g. `"SIGUSR1"`.
+
+Your plugin or barlib can call `pthread_sigmask()` (and, consequently,
+`pselect()`).
+
+Writing a plugin
+===
+Copy `include/plugin_data.h`, `include/plugin_data_v1.h`, `include/plugin_v1.h` and `include/common.h`;
+include `include/plugin_v1.h` and start reading `include/plugin_data.h`.
+
+Then, declare a global `const LuastatusIfacePlugin luastatus_iface_plugin_v1` variable.
+
+Writing a barlib
+===
+Copy `include/barlib_data.h`, `include/barlib_data_v1.h`, `include/barlib_v1.h` and `include/common.h`;
+include `include/barlib_v1.h` and start reading `include/barlib_data.h`.
+
+Then, declare a global `const LuastatusIfaceBarlib luastatus_iface_barlib_v1` variable.

DOCS/c_notes/eintr-policy.md

@@ -0,0 +1,5 @@
+The main problem is that all the stdio functions may, according to POSIX, fail with `EINTR`, and there is no way to restart some of them, e.g. `fprintf`.
+
+Our solution is to ensure that `SA_RESTART` is set for all the signals that could be raised (without terminating the program).
+
+See also: http://man7.org/linux/man-pages/man7/signal.7.html, section "Interruption of system calls and library functions by signal handlers".

DOCS/c_notes/empty-ranges-and-c-stdlib.md

@@ -0,0 +1,45 @@
+http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf
+
+Subclause 7.1.4 Use of library functions, point 1:
+
+> Each of the following statements applies unless explicitly stated otherwise in the
+> detailed descriptions that follow: If an argument to a function has an invalid value (such
+> as a value outside the domain of the function, or a pointer outside the address space of
+> the program, or a null pointer, or a pointer to non-modifiable storage when the
+> corresponding parameter is not const-qualified) or a type (after promotion) not expected
+> by a function with variable number of arguments, the behavior is undefined. If a function
+> argument is described as being an array, the pointer actually passed to the function shall
+> have a value such that all address computations and accesses to objects (that would be
+> valid if the pointer did point to the first element of such an array) are in fact valid.
+
+It’s not OK to call any function defined in `<string.h>` with a pointer that can’t be dereferenced:
+
+Subclause 7.21.1 String handling conventions, point 2:
+
+> Where an argument declared as `size_t n` specifies the length of the array for a function, `n`
+> can have the value zero on a call to that function. Unless explicitly stated otherwise in
+> the description of a particular function in this subclause, pointer arguments on such a
+> call shall still have valid values, as described in 7.1.4. On such a call, a function
+> that locates a character finds no occurrence, a function that compares two character
+> sequences returns zero, and a function that copies characters copies zero characters.
+
+It’s not OK to call `qsort`/`bsearch` with a pointer that can’t be dereferenced:
+
+Subclause 7.20.5 Searching and sorting utilites, point 1:
+
+> These utilities make use of a comparison function to search or sort arrays of unspecified
+> type. Where an argument declared as `size_t nmemb` specifies the length of the array for a
+> function, `nmemb` can have the value zero on a call to that function; the comparison function
+> is not called, a search finds no matching element, and sorting performs no rearrangement.
+> Pointer arguments on such a call shall still have valid values, as described in 7.1.4.
+
+However, it’s OK to call `snprintf`/`vsnprintf` with a pointer that can’t be dereferenced, as long as `n` is zero:
+
+Subclause 7.19.6.5 The `snprintf` function, point 2:
+
+> The `snprintf` function is equivalent to `fprintf`, except that the output is written into an
+> array (specified by argument `s`) rather than to a stream. If `n` is zero, nothing is written, and
+> `s` may be a null pointer. Otherwise, output characters beyond the `n-1`st are discarded rather
+> than being written to the array, and a null character is written at the end of the characters
+> actually written into the array. If copying takes place between objects that overlap, the behavior
+> is undefined.

DOCS/design/map_get.md

@@ -0,0 +1,15 @@
+luastatus provides the following function to barlibs and plugins:
+
+````c
+void ** (*map_get)(void *userdata, const char *key);
+````
+
+This function is **not** thread-safe and should only be used in the `init` function.
+
+luastatus maintains a global mapping from zero-terminated strings to pointers (`void *`).
+`map_get` returns a pointer to the pointer corresponding to the given key; if a map entry with the given key does not exist, it creates one with a null pointer value.
+
+You can read and/or write from/to this pointer-to-pointer; it is guaranteed to be persistent across other calls to `map_get` and other functions.
+However, note that it is **not** `void *volatile *`, so you should not write to it from functions other than `init`.
+
+Its intended use is for synchronization.