0b5c0c9c868213fee1a8e3b571a96e2e099e8e1e
docs/SupportLibrary.rst | 247 ++++++++++++++++++++++++++++++++++++++++++++++++
docs/SystemLibrary.rst | 247 ------------------------------------------------
docs/index.rst | 6 +-
3 files changed, 250 insertions(+), 250 deletions(-)
diff --git a/docs/SupportLibrary.rst b/docs/SupportLibrary.rst
new file mode 100644
index 0000000..36ab49a
--- /dev/null
+++ b/docs/SupportLibrary.rst
@@ -0,0 +1,247 @@
This will break existing URLs. Until we have a way to set up redirects the file name should stay the same.
– Sean Silva
This patch has changed "System V IPC" to "Support V IPC". This seems to be an accident caused by some sort of automation.
OK, I'll resubmit it.
0dd2e7b681c2c909deaaeb85b5018e1f6b8dd358
docs/SupportLibrary.rst | 247 ++++++++++++++++++++++++++++++++++++++++++++++++
docs/SystemLibrary.rst | 247 ------------------------------------------------
docs/index.rst | 6 +-
3 files changed, 250 insertions(+), 250 deletions(-)
diff --git a/docs/SupportLibrary.rst b/docs/SupportLibrary.rst
new file mode 100644
index 0000000..4c6226c
--- /dev/null
+++ b/docs/SupportLibrary.rst
@@ -0,0 +1,247 @@
This will break existing URLs. Until we have a way to set up redirects the
file name should stay the same.
Would a SystemLibrary.rst saying it was replaced with the support library be ok?
-- Sean Silva
Cheers,
Rafael
From 1d658dd52ca3973109e370103a7dd3485a4ee11f Mon Sep 17 00:00:00 2001
ping,is there any other problems in this patch?
在 2013-5-27 上午12:09，“罗勇刚(Yonggang Luo)” <luoyonggang@gmail.com>写道：
I think it is fine, but please wait for Sean to confirm.
AFAIK, libSupport does more than what this document describes (for example,
it contains ADT, which are portable and not system-specific, contrary to
the second paragraph of the document). Does it make sense to just globally
replace "Support" for "System"? I wasn't around when the transition was
made, so I don't know. Please get a confirmation from someone who can speak
authoritatively about the transition from libSystem to libSupport. Other
than that, LGTM.
Also, I would expect a follow-up patch for lib/Support/README.txt.system
after this patch has landed.
btw, in the future please attach the patch rather than including it
directly in the body of the message.
-- Sean Silva
AFAIK, libSupport does more than what this document describes (for example,
it contains ADT, which are portable and not system-specific, contrary to the
second paragraph of the document). Does it make sense to just globally
replace "Support" for "System"? I wasn't around when the transition was
made, so I don't know. Please get a confirmation from someone who can speak
authoritatively about the transition from libSystem to libSupport. Other
than that, LGTM.
System got merged into Support a long time ago. We could improve the
documentation of what lib/Support is, but this is a good start IMHO.
Cheers,
Rafael
Ah, ok. In that case, I think that it would be best to make a new page for
libSupport, and have it defer to SystemLibrary.rst for discussion of the
"libSystem" parts of libSupport. The major necessary changes for
SystemLibrary.rst would then be to mention its inclusion in libSupport
(important) and fix file paths (mechanical, less important).
-- Sean Silva
Looking for suggestion about Support library document improvement.
Ah, ok. In that case, I think that it would be best to make a new page for
libSupport, and have it defer to SystemLibrary.rst for discussion of the
"libSystem" parts of libSupport. The major necessary changes for
SystemLibrary.rst would then be to mention its inclusion in libSupport
(important) and fix file paths (mechanical, less important).
Sorry, but at least for me having a docs/SystemLibrary.rst and so
lib/System is very confusing. Ideally we would have a
docs/SystemLibrary.rst that would just says "this library has been
merged to lib/Support" and docs/SupportLibrary.rst documents whatever
is in lib/Support.
Cheers,
Rafael
> Ah, ok. In that case, I think that it would be best to make a new page
for
> libSupport, and have it defer to SystemLibrary.rst for discussion of the
> "libSystem" parts of libSupport. The major necessary changes for
> SystemLibrary.rst would then be to mention its inclusion in libSupport
> (important) and fix file paths (mechanical, less important).Sorry, but at least for me having a docs/SystemLibrary.rst and so
lib/System is very confusing.
As I mentioned, for the moment the page should (probably in its first
sentence) mention that the code has been merged into libSupport and that it
doesn't exist in the tree as lib/System. Simply replacing "System" with
"Support" doesn't really buy anything, besides misrepresenting what
libSupport actually is (consider the second sentence of <
http://llvm.org/docs/SystemLibrary.html> (describing the purpose), which is
not accurate about libSupport as a whole).
Ideally we would have a
docs/SystemLibrary.rst that would just says "this library has been
merged to lib/Support" and docs/SupportLibrary.rst documents whatever
is in lib/Support.
Considering our OS portability layer to be it's own separate thing, even if
it isn't its own lib/* directory is probably a good distinction to make
regardless. And SystemLibrary.rst is well-written and has excellent,
focused content about LLVM's approach to OS portability.
After thinking about this a bit more, it's not clear to me that it would be
beneficial to include this content into a general page about libSupport, as
that would make it less focused and harder to find. If anything, it would
be "ideal" to put it into a file Portability.rst (or similar), but that's a
marginal benefit anyway since it is already one of the top hits when
searching "llvm portability". We can really easily massage the title and
content (such as referenced file paths), like what happended to
clang/docs/Tooling.rst, which is now "Choosing the Right Interface for Your
Application" <http://clang.llvm.org/docs/Tooling.html>.
-- Sean Silva
Ideally we would have a
docs/SystemLibrary.rst that would just says "this library has been
merged to lib/Support" and docs/SupportLibrary.rst documents whatever
is in lib/Support.Considering our OS portability layer to be it's own separate thing, even if
it isn't its own lib/* directory is probably a good distinction to make
regardless. And SystemLibrary.rst is well-written and has excellent, focused
content about LLVM's approach to OS portability.After thinking about this a bit more, it's not clear to me that it would be
beneficial to include this content into a general page about libSupport, as
that would make it less focused and harder to find. If anything, it would be
"ideal" to put it into a file Portability.rst (or similar), but that's a
marginal benefit anyway since it is already one of the top hits when
searching "llvm portability". We can really easily massage the title and
content (such as referenced file paths), like what happended to
clang/docs/Tooling.rst, which is now "Choosing the Right Interface for Your
Application" <http://clang.llvm.org/docs/Tooling.html>.
That is ok. It is the reference to libSystem that is confusing, so
making this file about the "portability features in lib/Support" would
be great!
-- Sean Silva
Cheers,
Rafael
I hit upon docs/SystemLibrary.rst today.
Is this documentation useful to anyone? Can I delete it?
Most of the guidelines seem like common sense: Keeping LLVM Portable, High Level Interface, No Unused Functionality, No Duplicate Implementations, etc.
Some are not really true, like “Minimize Soft Errors”. We currently propagate a lot of file-related soft errors up as llvm::error_codes.
Only a few seem useful to me: Don’t Expose System Headers (basically, no windows.h) and No Virtual Methods.
I hit upon docs/SystemLibrary.rst today.
Is this documentation useful to anyone? Can I delete it?
Most of the guidelines seem like common sense: Keeping LLVM Portable, High
Level Interface, No Unused Functionality, No Duplicate Implementations, etc.
They aren't all written down elsewhere, so I oppose removing them. Also, as
a general rule, I look with extreme scrutiny at anything that would break
the validity of existing URL's.
Some are not really true, like "Minimize Soft Errors". We currently
propagate a lot of file-related soft errors up as llvm::error_codes.
Please fix that one to describe the current best-practices for error
handling.
-- Sean Silva