CODING_STYLE: document src/shared ←→ src/basic split

Addresses: https://github.com/systemd/systemd/pull/3580#issuecomment-227931168

While we are at it, also document that we focus on glibc, not any other libcs.

diff --git a/CODING_STYLE b/CODING_STYLE
index f31d76f8cef5a789f169bf53ec48b5e524ff87c8..43cf57a49f7764e6c8832247886a48d12dfc5c13 100644 (file)
--- a/CODING_STYLE
+++ b/CODING_STYLE
@@ -406,3 +406,26 @@
   shorts as their name would suggest, but on uint32_t and uint16_t. Also,
   "network byte order" is just a weird name for "big endian", hence we might
   want to call it "big endian" right-away.
+
+- You might wonder what kind of common code belongs in src/shared/ and what
+  belongs in src/util/. The split is like this: anything that uses public APIs
+  we expose (i.e. any of the sd-bus, sd-login, sd-id128, ... APIs) must be
+  located in src/shared/. All stuff that only uses external libraries from
+  other projects (such as glibc's APIs), or APIs from src/basic/ itself should
+  be placed in src/basic/. Conversely, src/libsystemd/ may only use symbols
+  from src/basic, but not from src/shared/. To summarize:
+
+  src/basic/      → may be used by all code in the tree
+                  → may not use any code outside of src/basic/
+
+  src/shared/     → may be used by all code in the tree, except for code in src/basic/
+                  → may not use any code outside of src/basic/, src/shared/, src/libsystemd/
+
+  src/libsystemd/ → may be used by all code in the tree, except for code in src/basic/
+                  → may not use any code outside of src/basic/, src/shared/, src/libsystemd/
+
+- Our focus is on the GNU libc (glibc), not any other libcs. If other libcs are
+  incompatible with glibc it's on them. However, if there are equivalent POSIX
+  and Linux/GNU-specific APIs, we generally prefer the POSIX APIs. If there
+  aren't, we are happy to use GNU or Linux APIs, and expect non-GNU
+  implementations of libc to catch up with glibc.