abseil / abseil.github.io

Abseil documentation abseil.io

abseil.github.io

Adding readme content here

abseil.github.io's Issues

[Bug]: Document the c++14 bazel footgun

Describe the issue

abseil requires c++14 or greater. The current version of bazel, out of the box, doesn't pass the necessary flags to enable c++14 or greater, resulting in an error when you try to follow the abseil bazel quickstart. I understand that work is in progress (bazelbuild/bazel#18181) to address this in bazel, but in the meantime please consider updating the quickstart. The quickstart should be as easy to use as possible, and yet as written it sends the reader on a merry chase to stackoverflow etc just to get a hello world integration with abseil to work. That shouldn't be necessary, and seems like it'd act as a repellent to new users.

Steps to reproduce the problem

Follow the quickstart

What version of Abseil are you using?

20230125.1

What operating system and version are you using?

OS X 13.3.1a

What compiler and version are you using?

Using built-in specs.
COLLECT_GCC=gcc
COLLECT_LTO_WRAPPER=/usr/lib/gcc/x86_64-linux-gnu/11/lto-wrapper
OFFLOAD_TARGET_NAMES=nvptx-none:amdgcn-amdhsa
OFFLOAD_TARGET_DEFAULT=1
Target: x86_64-linux-gnu
Configured with: ../src/configure -v --with-pkgversion='Ubuntu 11.3.0-1ubuntu122.04' --with-bugurl=file:///usr/share/doc/gcc-11/README.Bugs --enable-languages=c,ada,c++,go,brig,d,fortran,objc,obj-c++,m2 --prefix=/usr --with-gcc-major-version-only --program-suffix=-11 --program-prefix=x86_64-linux-gnu- --enable-shared --enable-linker-build-id --libexecdir=/usr/lib --without-included-gettext --enable-threads=posix --libdir=/usr/lib --enable-nls --enable-bootstrap --enable-clocale=gnu --enable-libstdcxx-debug --enable-libstdcxx-time=yes --with-default-libstdcxx-abi=new --enable-gnu-unique-object --disable-vtable-verify --enable-plugin --enable-default-pie --with-system-zlib --enable-libphobos-checking=release --with-target-system-zlib=auto --enable-objc-gc=auto --enable-multiarch --disable-werror --enable-cet --with-arch-32=i686 --with-abi=m64 --with-multilib-list=m32,m64,mx32 --enable-multilib --with-tune=generic --enable-offload-targets=nvptx-none=/build/gcc-11-xKiWfi/gcc-11-11.3.0/debian/tmp-nvptx/usr,amdgcn-amdhsa=/build/gcc-11-xKiWfi/gcc-11-11.3.0/debian/tmp-gcn/usr --without-cuda-driver --enable-checking=release --build=x86_64-linux-gnu --host=x86_64-linux-gnu --target=x86_64-linux-gnu --with-build-config=bootstrap-lto-lean --enable-link-serialization=2
Thread model: posix
Supported LTO compression algorithms: zlib zstd
gcc version 11.3.0 (Ubuntu 11.3.0-1ubuntu122.04)

What build system are you using?

bazel 6.1.2

Additional context

No response

SWE book PDF

Is there a reason to no longer include the SWE book as pdf reference? Having an HTML rendering is really useful for mobile consumption but source code highlighting like in the PDF version is quite nice. Would you accept PRs increasing optics?

To be clear: being able to access the book at all is fantastic

CMake/Bazel quickstart malformed link

Near the top of CMake/Bazel quickstart guides are the links to the other, these return 404 due to linking to paths with the .md suffixes - these suffixes need to be removed.

Wording in TotW 153 "Don't use using-directives" may mislead readers

Thanks to all involved in the work on all the Abseil TotW material - it's a fantastic resource.

I have some feedback on TotW #153 "Don't use using-directives". I realise this is unsolicited so please accept my apologies if it is unwelcome and/or wrong.

I think the paragraph:

The vast majority of C++ users think that the using-directive is injecting names into the scope where it’s declared. In the example above, that would be the scope of the function. In reality, the names are injected into the nearest common ancestor of the target namespace (::testing) and the usage namespace (::totw::example::anonymous). In our example, that’s the global namespace!

…is worded in a way that risks misleading readers. Or to put it more honestly: I got myself a bit confused by its wording ;).

AFAIU (from http://eel.is/c++draft/basic.namespace#namespace.udir-2 ), there are two relevant scopes here:

1. the scope within which the names are available for use in unqualified lookup
2. the scope in which any such unqualified lookup will treat them as if they reside

I think the above paragraph is correctly highlighting that the lookup-as-if scope is the nearest common ancestor scope:

1. availability : scope of using directive ✔️
2. lookup-as-if : nearest common ancestor scope ✔️

…but I think the paragraph's wording conflates these two notions and hence risks misleading readers into thinking that both these notions use the nearest common ancestor scope, ie that:

1. availability : nearest common ancestor scope ❌
2. lookup-as-if : nearest common ancestor scope ✔️

…and I think opening sentence will prime readers to be particularly susceptible to accepting a claim they find highly counter-intuitive. Furthermore, I think the code snippet that follows after the paragraph reinforces the misunderstanding by drawing an equivalence with a dump of using declarations in the global namespace.

In case it's helpful, here's one possible attempt at another wording:

[…] In reality, though the names it injects are indeed only accessible within that scope, any unqualified lookup of those names within that scope will treat the names as having been injected into the nearest common ancestor of the target namespace […]

(FWIW, for my tastes, I also think this tip overstates the applicability of the rule. I absolutely agree with its applicability for Google-like code-base sizes, predicted project lifetimes, dependency loads, availability of tooling/support etc. But I think violation of the rule may be completely reasonable in other contexts that involve wildly different trade-offs.)

I hope that you find this issue more helpful than annoying.

Unreadable footer area

The footer should be improved to have higher contrast.

This is a screenshot using Chrome under Linux:

Asking for permission to translate SWE books.

Hi, I'm a developer working on South Korea. First of all, I'm not good at in english. So please understand my awkward English skills.

And sorry for remaining question here, because I know this is not a right place for this sort of question. However, I heard the news the book was free from here, and I couldn't find a suitable community to inquire, so I remain question here.

Anyway I want to asking for is it okay for translating SWE book to Korean. From the moment I found out that this book existed, that it was free, and that there was no translation, I have wanted to translate it. A few months after I started reading books while translating, and I just finished it. I worked that on my private repository and now I hope to turn it to the public github web page.

And before switching to public, I ask is it okay to switch. I have no thoughts about commercial use. And of course, if you want, I won't switch.

I've always been interested in Google's development culture. Personally, I was greatly influenced by reading the book, and I would like to contribute even a little to Korea's development culture.

I look forward to your reply. Have a nice day.

TotW Frequency

How frequent are the TotW going to be posted? When I watched Titus talk. I think he said they are more than 120. If its one per week then 2 years ???

Subscribe to TotW by email/RSS

Is it possible to create a RSS feed or an email subscription for when you release TotW? I'd love to learn more about C++ but I'm afraid I'll forget to come back and read the latest and greatest.

Missing semicolon on private constructor in tip 42

I think you meant:

...
private:
  // Clients can't invoke the constructor directly.
  Foo();

C++ quickstart need add com_github_google_benchmark rule in WORKSPACE

I follow https://abseil.io/docs/cpp/quickstart.html Set Up a Bazel Workspace to Work with Abseil instructions to setup bazel, but run command bazel test --test_tag_filters=-benchmark @com_google_absl//... failed with following error:

 no such package '@com_github_google_benchmark//': The repository '@com_github_google_benchmark' could not be resolved and referenced by '@com_google_absl//absl/time/internal/cctz:cctz_benchmark'

So I Copy com_github_google_benchmark rule from Abseil WORKSPACE file and it works.

Maybe we need add com_github_google_benchmark into WORKSPACE for quickstart instruction

Jekyll adds arbitrary <a> tags

Which lead to CSS highlighting, presuming they are links. Can fix through CSS, but would like to know why the tags are being added.

GET STARTED link is broken

The GET STARTED link on the main page is broken. The page it links to no longer exists.

abseil.github.io/_includes/hero.html

Line 10 in 938f2d6

<a href="{{site.baseurl}}/docs/cpp.html">

links on docs 404

link to: https://abseil.io/docs/cpp/guides/numbers.h
from: https://abseil.io/docs/cpp/guides/strings#numericConversion

leads to 404

Feature request: TotW epub downloads

Hi,

It would we nice to have ability to read TotW on e-reader via .epub file, downloadable from abseil.io. Who needs fiction literature when we have these gems? :)

Probably some script could build .ebup from bunch of Markdown files available.

TotW list formatting is broken on mobile

It looks like there's some line-height issues causing text to be overlaid. This appears on mobile and more generally when the view width is relatively narrow:

Code samples in TOTW limited to 61 character width

See, for instance, https://abseil.io/tips/totw/1

The main text section is too narrow, and only fits 61 characters. You have to scroll horizontally to read the comments. The code blocks really should fit 80 characters, since all code in TOTW is going to be formatted for that width.

Text on pages is really hard to read

Pages like http://abseil.io/about/philosophy use a gray font with a font-weight below "normal". Depending on your screen technology / OS, this comes out as very thin lines that aren't even black.

Here are Google's docs on proper use of contrast, in case they are helpful:
https://developers.google.com/web/fundamentals/accessibility/accessible-styles#color_and_contrast

Appstore

Homepage content isn't centered

The content of the homepage isn't centered, see screenshot below.

(Screenshot taken from Chrome running on MacOS.)

The container is aligned to the left (which is for the docs I suppose), which causes this behaviour.

Hihp

Prettyprinter can't be disabled for ``` markdown

Will need to look at our prettyprinter. Tried to disable syntax highlighting with sh or text and neither worked.

C++ devguide should include necessary #includes

I'm looking at https://abseil.io/docs/cpp/guides/strings, and it would be very useful if it told me which #include I need for each function. It looks like all of the guides could benefit from this.

TotW 5 shows twice in sitemap

On https://abseil.io/tips/, I see:
TotW #3: String Concatenation and operator+ vs. StrCat()
TotW #5: Disappearing Act
TotW #5: Disappearing Act
TotW #10: Splitting Strings, not Hairs

i.e., TotW #5 shows twice. Seems like a mistake.

Interactive table for "Tips of the Week"

I can understand why Abseil team prefers keeping the original numbering scheme and original publication date, but external readers who regularly return to check for new posts, it is not immediately clear whether there is a new post after scanning the list in https://abseil.io/tips/.

Perhaps the <ul> list can be converted into an interactive <table> that can be sorted based on either original numbering scheme or external publication date?

May Google release more ToTW to public?

Hi maintainer,

The ToTW is really useful to all developers, I wonder whether Google could release the more topics of ToTW?

Add ability of pre.bad-code to override pre.prettyprint borders

Specifically, I'd like to add:

border-left: 2px solid;
border-left-color: #c53929;

but these are currently colliding with pre.prettyprint in prettify.js, which sets the border to 1px solid black (and is overridden in the existing CSS).

operator<< for StrAppend

Abseil looks very interesting!

I've been using StrAppend-like and StrCat-like functions for some time now and they work great.
I use operator<< for StrAppend though, which looks very natural. Could Abseil consider supporting this?

Logging documentation should explain InitializeLog and SetStderrThreshold

Describe the issue

I developed a C++ service that uses Abseil logging and I could not figure out why my log messages with INFO severity did not appear in the Linux systemd journal. I reviewed https://abseil.io/docs/cpp/guides/logging and its information about log severity, and I tried defining ABSL_MIN_LOG_LEVEL to 0, but it did not help.

I had previously added a call to absl::InitializeLog() (which is not explained in that docs page) in order to eliminate this warning from my server's output: WARNING: All log messages before absl::InitializeLog() is called are written to STDERR. I eventually figured out to my dismay that removing this call to InitializeLog() was all I needed to fix my problem: INFO log messages now appeared in the journal output.

I eventually stumbled upon an example that showed me how to properly initialize Abseil logging by calling absl::SetStderrThreshold() in addition to InitializeLog(). That led me to globals.h which also explains that --minloglevel can be used to control this behavior.

I feel misled since Abseil told me to call InitializeLog(), but it didn't tell me that I might also need to call SetStderrThreshold(). I did the right thing and read the documentation, but none of InitializeLog(), SetStderrThreshold() or --minloglevel are mentioned at all at https://abseil.io/docs/cpp/guides/logging. It would be great if this documentation could be improved, it would have saved me quite a bit of troubleshooting.

Steps to reproduce the problem

Write a C++ service with a main that begins with:

int main(int argc, char **argv) {
  absl::InitializeLog();
  absl::ParseCommandLine(argc, argv);

Add some LOG(INFO) and LOG(ERROR) messages in the service. Build it and register the service with systemd on a Linux system. Start the service then run journalctl -u <service-name>. Observe that the log messages with INFO severity do not appear in the journal, but the messages with ERROR severity do.

Add a call to absl::SetStderrThreshold(absl::LogSeverityAtLeast::kInfo); at the start of main(), rebuild and restart the service and observe that now INFO log messages appear in the journal.

What version of Abseil are you using?

https://github.com/abseil/abseil-cpp/archive/1adf896ec842bd9788a1bbede94a33e1402b8ecb.tar.gz

What operating system and version are you using?

Linux ARM64

What compiler and version are you using?

gcc

What build system are you using?

Bazel 6.0.0

Additional context

No response

Header collapses incorrectly

When the header collapses, which occurs when you scroll down, it collapses in an incorrect fashion. (See screenshot below.)

(Screenshot taken from Chrome running on MacOS.)

No tag should appear in the html title

Let’s take, for example, https://abseil.io/tips/134

In the browser tab and history, the title appear as abseil / Tip of the Week #134: <code>make_unique</code> and <code>private</code> Constructors

You probably would want to strip tag when displaying it in the HTML head

Feed Validation Error: RSS 2.0 instead Atom

Hi,
I have a small problem with the feed for publication dates that are not correctly detected in Liferea, the 'news reader' I currently use .
Searching on 'Jekyll' doc and for Jekyll Feed plugin it seems that feed.xml is classified as 'RSS 2.0' (rss version="2.0") but coded as 'Atom'.
For the validation I also used the W3C Validator site.
Having the 'jekyll/jekyll-feed' feed.xml as reference I did some local tests by changing some xml fields to get the validation and I came to have an acceptable situation (only some validation warning) with the attached changes.
I attach the changes here as not knowing the site and all its information are unable to build a dedicated pull request with all correct data for the feed.

Thanks for your work.
Enrico

feed-atom-test.patch

diff --git a/feed.xml b/feed.xml
index 8e7a351..aa36233 100644
--- a/feed.xml
+++ b/feed.xml
@@ -2,22 +2,27 @@
 layout: null
 ---
 <?xml version="1.0" encoding="utf-8"?>
-<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
-  <channel>
+<feed xmlns="http://www.w3.org/2005/Atom" {% if site.lang %}xml:lang="{{ site.lang }}"{% endif %}>
     <title>Abseil Blog &amp; Tips</title>
-    <description>An open-source collection of C++ library code designed to
-    augment the C++ standard library</description>
-    <link>{{ site.url }}</link>
+    <subtitle>An open-source collection of C++ library code designed to
+    augment the C++ standard library</subtitle>
+    <updated>{{ site.time | date_to_xmlschema }}</updated>
+    <id>{{ site.url | xml_escape }}</id>
     {% for post in site.posts %}
       {% unless post.draft %}
-        <item>
-          <title>{{ post.title | xml_escape }}</title>
-          <description>{{ post.content | xml_escape }}</description>
-          <pubDate>{{ post.date | date_to_xmlschema }}</pubDate>
-          <link>{{ post.url | prepend: site.url }}</link>
-          <guid isPermaLink="true">{{ post.url | prepend: site.url }}</guid>
-        </item>
+        <entry>
+          <title type="html">{{ post.title | xml_escape }}</title>
+          <content type="html">{{ post.content | xml_escape }}</content>
+          <published>{{ post.date | date_to_xmlschema }}</published>
+          <updated>{{ post.date | date_to_xmlschema }}</updated>
+          <link href="{{ post.url | prepend: site.url }}" />
+          <author>
+            <name>{{ post_author_name | default: "???" | xml_escape }}</name>
+          </author>
+          <link href="{{ post.url | prepend: site.url }}" type="text/html" title="{{ post_title }}" />
+          <id>{{ post.id | absolute_url | xml_escape }}</id>
+        </entry>
       {% endunless %}
     {% endfor %}
-  </channel>
-</rss>
\ No newline at end of file
+</feed>
+

http://abseil.io/blog RSS or Atom?

Is it a blog without a feed? ;-)