westonpace commented on a change in pull request #12241: URL: https://github.com/apache/arrow/pull/12241#discussion_r791327061
########## File path: docs/source/cpp/gdb.rst ########## @@ -0,0 +1,167 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, +.. software distributed under the License is distributed on an +.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +.. KIND, either express or implied. See the License for the +.. specific language governing permissions and limitations +.. under the License. + +.. default-domain:: cpp +.. highlight:: console + +========================== +Debugging code using Arrow +========================== + +GDB extension for Arrow C++ +=========================== + +By default, when asked to print the value of a C++ object, +`GDB <https://www.sourceware.org/gdb/>`_ displays the contents of its +member variables. However, for C++ objects this does not often yield +a very useful output, as C++ classes tend to hide their implementation details +behind methods and accessors. + +For example, here is how a :class:`arrow::Status` instance may be displayed +by GDB:: + + $3 = { + <arrow::util::EqualityComparable<arrow::Status>> = {<No data fields>}, + <arrow::util::ToStringOstreamable<arrow::Status>> = {<No data fields>}, + members of arrow::Status: + state_ = 0x0 + } + +and here is a :class:`arrow::Decimal128Scalar`:: + + $4 = (arrow::Decimal128Scalar) { + <arrow::DecimalScalar<arrow::Decimal128Type, arrow::Decimal128>> = { + <arrow::internal::PrimitiveScalarBase> = { + <arrow::Scalar> = { + <arrow::util::EqualityComparable<arrow::Scalar>> = {<No data fields>}, + members of arrow::Scalar: + _vptr.Scalar = 0x7ffff6870e78 <vtable for arrow::Decimal128Scalar+16>, + type = std::shared_ptr<arrow::DataType> (use count 1, weak count 0) = { + get() = 0x555555ce58a0 + }, + is_valid = true + }, <No data fields>}, + members of arrow::DecimalScalar<arrow::Decimal128Type, arrow::Decimal128>: + value = { + <arrow::BasicDecimal128> = { + <arrow::GenericBasicDecimal<arrow::BasicDecimal128, 128, 2>> = { + static kHighWordIndex = <optimized out>, + static kBitWidth = 128, + static kByteWidth = 16, + static LittleEndianArray = <optimized out>, + array_ = { + _M_elems = {[0] = 1234567, [1] = 0} + } + }, + members of arrow::BasicDecimal128: + static kMaxPrecision = 38, + static kMaxScale = 38 + }, <No data fields>} + }, <No data fields>} + +Fortunately, GDB also allows custom extensions to override the default printing +for specific types. We provide a +`GDB extension <https://github.com/apache/arrow/blob/master/cpp/gdb_arrow.py>`_ +written in Python that enables pretty-printing for common Arrow C++ classes, +so as to enable a more productive debugging experience. For example, +here is how the aforementioned :class:`arrow::Status` instance will be +displayed:: + + $5 = arrow::Status::OK() + +and here is the same :class:`arrow::Decimal128Scalar` instance as above:: + + $6 = arrow::Decimal128Scalar of value 123.4567 [precision=10, scale=4] + + +Manual loading +-------------- + +To enable the GDB extension for Arrow, you can simply +`download it <GDB extension>`_ +somewhere on your computer and ``source`` it from the GDB prompt:: + + (gdb) source path/to/gdb_arrow.py + +You will have to ``source`` it on each new GDB session. You might want to +make this implicit by adding the ``source`` invocation in a +`gdbinit <https://sourceware.org/gdb/onlinedocs/gdb/gdbinit-man.html>`_ file. + + +Automatic loading +----------------- + +GDB provides a facility to automatically load scripts or extensions for each +object file or library that is involved in a debugging session. You will need +to: + +1. Find out what the *auto-load* location(s) is/are for your GDB install. Review comment: ```suggestion 1. Find out what the *auto-load* locations are for your GDB install. ``` We can probably stick with the plural here, even if there could possibly be one location. It's just a touch easier to read. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
