diff options
Diffstat (limited to 'llvm/docs')
| -rw-r--r-- | llvm/docs/CommandGuide/llvm-config.rst | 5 | ||||
| -rw-r--r-- | llvm/docs/GettingInvolved.rst | 2 | ||||
| -rw-r--r-- | llvm/docs/LangRef.rst | 22 | ||||
| -rw-r--r-- | llvm/docs/MIRLangRef.rst | 56 | ||||
| -rw-r--r-- | llvm/docs/ProgrammersManual.rst | 82 | ||||
| -rw-r--r-- | llvm/docs/ReleaseNotes.md | 4 |
6 files changed, 90 insertions, 81 deletions
diff --git a/llvm/docs/CommandGuide/llvm-config.rst b/llvm/docs/CommandGuide/llvm-config.rst index 63658d0..1c5c9c7 100644 --- a/llvm/docs/CommandGuide/llvm-config.rst +++ b/llvm/docs/CommandGuide/llvm-config.rst @@ -126,6 +126,11 @@ OPTIONS Print the installation prefix for LLVM. +**--quote-paths** + + Quote and escape paths when needed, most notably when a quote, space, backslash + or dollar sign characters are present in the path. + **--shared-mode** Print how the provided components can be collectively linked (`shared` or `static`). diff --git a/llvm/docs/GettingInvolved.rst b/llvm/docs/GettingInvolved.rst index 039d616..0dba941 100644 --- a/llvm/docs/GettingInvolved.rst +++ b/llvm/docs/GettingInvolved.rst @@ -225,7 +225,7 @@ what to add to your calendar invite. - * - GlobalISel - Every 2nd Tuesday of the month - - `gcal <https://calendar.google.com/calendar/u/0?cid=ZDcyMjc0ZjZiZjNhMzFlYmE3NTNkMWM2MGM2NjM5ZWU3ZDE2MjM4MGFlZDc2ZjViY2UyYzMwNzVhZjk4MzQ4ZEBncm91cC5jYWxlbmRhci5nb29nbGUuY29t>`__ + - `gcal <https://calendar.google.com/calendar/u/0?cid=YWZjNzhmMzE4MDNlNTAyNGY1NmE1MDIyODY0YTYwZmJmYzRjYTEwNTE1NmUxODA2NzBkYTliY2ZhYTVkNjk0NUBncm91cC5jYWxlbmRhci5nb29nbGUuY29t>`__ - `Meeting details/agenda <https://docs.google.com/document/d/1Ry8O4-Tm5BFj9AMjr8qTQFU80z-ptiNQ62687NaIvLs/edit?usp=sharing>`__ diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst index 54c7d0f..3c089b5 100644 --- a/llvm/docs/LangRef.rst +++ b/llvm/docs/LangRef.rst @@ -668,7 +668,7 @@ representation is not just an integer address are called "non-integral". Non-integral pointers have at least one of the following three properties: * the pointer representation contains non-address bits -* the pointer representation is unstable (may changed at any time in a +* the pointer representation is unstable (may change at any time in a target-specific way) * the pointer representation has external state @@ -757,7 +757,7 @@ The following restrictions apply to IR level optimization passes: The ``inttoptr`` instruction does not recreate the external state and therefore it is target dependent whether it can be used to create a dereferenceable -pointer. In general passes should assume that the result of such an inttoptr +pointer. In general passes should assume that the result of such an ``inttoptr`` is not dereferenceable. For example, on CHERI targets an ``inttoptr`` will yield a capability with the external state (the validity tag bit) set to zero, which will cause any dereference to trap. @@ -784,7 +784,7 @@ be performed as loads and stores of the correct type since stores of other types may not propagate the external data. Therefore it is not legal to convert an existing load/store (or a ``llvm.memcpy`` / ``llvm.memmove`` intrinsic) of pointer types with external -state to a load/store of an integer type with same bitwidth, as that may drop +state to a load/store of an integer type with the same bitwidth, as that may drop the external state. @@ -806,7 +806,7 @@ Global variables can optionally specify a :ref:`linkage type <linkage>`. Either global variable definitions or declarations may have an explicit section to be placed in and may have an optional explicit alignment specified. If there is a mismatch between the explicit or inferred section information for the -variable declaration and its definition the resulting behavior is undefined. +variable declaration and its definition, the resulting behavior is undefined. A variable may be defined as a global ``constant``, which indicates that the contents of the variable will **never** be modified (enabling better @@ -1334,7 +1334,7 @@ Currently, only the following parameter attributes are defined: The byval type argument indicates the in-memory value type. The byval attribute also supports specifying an alignment with the - align attribute. It indicates the alignment of the stack slot to + ``align`` attribute. It indicates the alignment of the stack slot to form and the known alignment of the pointer specified to the call site. If the alignment is not specified, then the code generator makes a target-specific assumption. @@ -1355,7 +1355,7 @@ Currently, only the following parameter attributes are defined: This is not a valid attribute for return values. - The alignment for an ``byref`` parameter can be explicitly + The alignment for a ``byref`` parameter can be explicitly specified by combining it with the ``align`` attribute, similar to ``byval``. If the alignment is not specified, then the code generator makes a target-specific assumption. @@ -1382,7 +1382,7 @@ Currently, only the following parameter attributes are defined: The preallocated attribute requires a type argument. The preallocated attribute also supports specifying an alignment with the - align attribute. It indicates the alignment of the stack slot to + ``align`` attribute. It indicates the alignment of the stack slot to form and the known alignment of the pointer specified to the call site. If the alignment is not specified, then the code generator makes a target-specific assumption. @@ -1550,7 +1550,7 @@ Currently, only the following parameter attributes are defined: ``nonnull`` This indicates that the parameter or return pointer is not null. This - attribute may only be applied to pointer typed parameters. This is not + attribute may only be applied to pointer-typed parameters. This is not checked or enforced by LLVM; if the parameter or return pointer is null, :ref:`poison value <poisonvalues>` is returned or passed instead. The ``nonnull`` attribute should be combined with the ``noundef`` attribute @@ -1558,7 +1558,7 @@ Currently, only the following parameter attributes are defined: ``dereferenceable(<n>)`` This indicates that the parameter or return pointer is dereferenceable. This - attribute may only be applied to pointer typed parameters. A pointer that + attribute may only be applied to pointer-typed parameters. A pointer that is dereferenceable can be loaded from speculatively without a risk of trapping. The number of bytes known to be dereferenceable must be provided in parentheses. It is legal for the number of bytes to be less than the @@ -1584,7 +1584,7 @@ Currently, only the following parameter attributes are defined: implies that a pointer is at least one of ``dereferenceable(<n>)`` or ``null`` (i.e., it may be both ``null`` and ``dereferenceable(<n>)``). This attribute may only be applied to - pointer typed parameters. + pointer-typed parameters. ``swiftself`` This indicates that the parameter is the self/context parameter. This is not @@ -1601,7 +1601,7 @@ Currently, only the following parameter attributes are defined: ``swifterror`` This attribute is motivated to model and optimize Swift error handling. It - can be applied to a parameter with pointer to pointer type or a + can be applied to a parameter with pointer-to-pointer type or a pointer-sized alloca. At the call site, the actual argument that corresponds to a ``swifterror`` parameter has to come from a ``swifterror`` alloca or the ``swifterror`` parameter of the caller. A ``swifterror`` value (either diff --git a/llvm/docs/MIRLangRef.rst b/llvm/docs/MIRLangRef.rst index 3f4c3cd..f7647c8 100644 --- a/llvm/docs/MIRLangRef.rst +++ b/llvm/docs/MIRLangRef.rst @@ -86,25 +86,25 @@ Tests are more accessible and future proof when simplified: - Use the ``-simplify-mir`` option with llc. - Machine function attributes often have default values or the test works just - as well with default values. Typical candidates for this are: `alignment:`, - `exposesReturnsTwice`, `legalized`, `regBankSelected`, `selected`. + as well with default values. Typical candidates for this are: ``alignment:``, + ``exposesReturnsTwice``, ``legalized``, ``regBankSelected``, ``selected``. The whole `frameInfo` section is often unnecessary if there is no special - frame usage in the function. `tracksRegLiveness` on the other hand is often + frame usage in the function. ``tracksRegLiveness`` on the other hand is often necessary for some passes that care about block livein lists. -- The (global) `liveins:` list is typically only interesting for early +- The (global) ``liveins:`` list is typically only interesting for early instruction selection passes and can be removed when testing later passes. - The per-block `liveins:` on the other hand are necessary if + The per-block ``liveins:`` on the other hand are necessary if `tracksRegLiveness` is true. -- Branch probability data in block `successors:` lists can be dropped if the +- Branch probability data in block ``successors:`` lists can be dropped if the test doesn't depend on it. Example: - `successors: %bb.1(0x40000000), %bb.2(0x40000000)` can be replaced with - `successors: %bb.1, %bb.2`. + ``successors: %bb.1(0x40000000), %bb.2(0x40000000)`` can be replaced with + ``successors: %bb.1, %bb.2``. - MIR code contains a whole IR module. This is necessary because there are no equivalents in MIR for global variables, references to external functions, - function attributes, metadata, debug info. Instead some MIR data references + function attributes, metadata, debug info. Instead, some MIR data references the IR constructs. You can often remove them if the test doesn't depend on them. @@ -114,16 +114,16 @@ Tests are more accessible and future proof when simplified: dropped: `:: (load 8)` - MIR blocks can reference IR blocks for debug printing, profile information, - or debug locations. Example: `bb.42.myblock` in MIR references the IR block - `myblock`. It is usually possible to drop the `.myblock` reference and simply - use `bb.42`. + or debug locations. Example: ``bb.42.myblock`` in MIR references the IR block + ``myblock``. It is usually possible to drop the ``.myblock`` reference and simply + use ``bb.42``. - If there are no memory operands or blocks referencing the IR, then the IR function can be replaced by a parameterless dummy function like - `define @func() { ret void }`. + ``define @func() { ret void }``. - It is possible to drop the whole IR section of the MIR file if it only - contains dummy functions (see above). The .mir loader will create the + contains dummy functions (see above). The ``.mir`` loader will create the IR functions automatically in this case. .. _limitations: @@ -131,7 +131,7 @@ Tests are more accessible and future proof when simplified: Limitations ----------- -Currently the MIR format has several limitations in terms of which state it +Currently, the MIR format has several limitations in terms of which state it can serialize: - The target-specific state in the target-specific ``MachineFunctionInfo`` @@ -150,7 +150,7 @@ These limitations impose restrictions on what you can test with the MIR format. For now, tests that would like to test some behaviour that depends on the state of temporary or local ``MCSymbol`` operands or the exception handling state in MMI, can't use the MIR format. As well as that, tests that test some behaviour -that depends on the state of the target specific ``MachineFunctionInfo`` or +that depends on the state of the target-specific ``MachineFunctionInfo`` or ``MachineConstantPoolValue`` subclasses can't use the MIR format at the moment. High Level Structure @@ -286,7 +286,7 @@ Example: Successors ^^^^^^^^^^ -The machine basic block's successors have to be specified before any of the +The machine basic block's successors must be specified before any of the instructions: .. code-block:: text @@ -489,13 +489,13 @@ In case this is true, the Machine Operand is printed according to the target. For example: -In AArch64RegisterInfo.td: +In ``AArch64RegisterInfo.td``: .. code-block:: text def sub_32 : SubRegIndex<32>; -If the third operand is an immediate with the value ``15`` (target-dependent +If the third operand is an immediate with the value ``15`` (a target-dependent value), based on the instruction's opcode and the operand's index the operand will be printed as ``%subreg.sub_32``: @@ -503,7 +503,7 @@ will be printed as ``%subreg.sub_32``: %1:gpr64 = SUBREG_TO_REG 0, %0, %subreg.sub_32 -For integers > 64 bits, we use a special machine operand, ``MO_CImmediate``, +For integers larger than 64 bits, we use a special machine operand, ``MO_CImmediate``, which stores the immediate in a ``ConstantInt`` using an ``APInt`` (LLVM's arbitrary-precision integers). @@ -552,7 +552,7 @@ corresponding internal ``llvm::RegState`` representation: * - ``implicit`` - ``RegState::Implicit`` - - Not emitted register (e.g. carry, or temporary result). + - Not emitted register (e.g., carry, or temporary result). * - ``implicit-def`` - ``RegState::ImplicitDefine`` @@ -625,7 +625,7 @@ For a CPI with the index 0 and offset -12: %1:gr64 = MOV64ri %const.0 - 12 -A constant pool entry is bound to a LLVM IR ``Constant`` or a target-specific +A constant pool entry is bound to an LLVM IR ``Constant`` or a target-specific ``MachineConstantPoolValue``. When serializing all the function's constants, the following format is used: @@ -670,12 +670,12 @@ a global value operand named ``G``: $rax = MOV64rm $rip, 1, _, @G, _ -The named global values are represented using an identifier with the '@' prefix. +The named global values are represented using an identifier with the ``@`` prefix. If the identifier doesn't match the regular expression -`[-a-zA-Z$._][-a-zA-Z$._0-9]*`, then this identifier must be quoted. +``[-a-zA-Z$._][-a-zA-Z$._0-9]*``, then this identifier must be quoted. The unnamed global values are represented using an unsigned numeric value with -the '@' prefix, like in the following examples: ``@0``, ``@989``. +the ``@`` prefix, as in the following examples: ``@0``, ``@989``. Target-dependent Index Operands ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -741,7 +741,7 @@ Example: MCSymbol Operands ^^^^^^^^^^^^^^^^^ -A MCSymbol operand holds a pointer to a ``MCSymbol``. For the limitations +An ``MCSymbol`` operand holds a pointer to an ``MCSymbol``. For the limitations of this operand in MIR, see :ref:`limitations <limitations>`. The syntax is: @@ -825,7 +825,7 @@ Comments ^^^^^^^^ Machine operands can have C/C++ style comments, which are annotations enclosed -between ``/*`` and ``*/`` to improve readability of e.g. immediate operands. +between ``/*`` and ``*/`` to improve readability of e.g., immediate operands. In the example below, ARM instructions EOR and BCC and immediate operands ``14`` and ``0`` have been annotated with their condition codes (CC) definitions, i.e. the ``always`` and ``eq`` condition codes: @@ -920,7 +920,7 @@ Instruction referencing locations This experimental feature aims to separate the specification of variable *values* from the program point where a variable takes on that value. Changes -in variable value occur in the same manner as ``DBG_VALUE`` meta instructions +in a variable value occur in the same manner as ``DBG_VALUE`` meta instructions but using ``DBG_INSTR_REF``. Variable values are identified by a pair of instruction number and operand number. Consider the example below: diff --git a/llvm/docs/ProgrammersManual.rst b/llvm/docs/ProgrammersManual.rst index 7b7a1ce..270a635 100644 --- a/llvm/docs/ProgrammersManual.rst +++ b/llvm/docs/ProgrammersManual.rst @@ -113,7 +113,7 @@ rarely have to include this file directly). ``isa<>``: The ``isa<>`` operator works exactly like the Java "``instanceof``" operator. - It returns true or false depending on whether a reference or pointer points to + It returns ``true`` or ``false`` depending on whether a reference or pointer points to an instance of the specified class. This can be very useful for constraint checking of various sorts (example below). @@ -167,7 +167,7 @@ rarely have to include this file directly). ``isa_and_present<>``: The ``isa_and_present<>`` operator works just like the ``isa<>`` operator, except that it allows for a null pointer as an argument (which it then - returns false). This can sometimes be useful, allowing you to combine several + returns ``false``). This can sometimes be useful, allowing you to combine several null checks into one. ``cast_if_present<>``: @@ -402,7 +402,7 @@ doxygen documentation or by looking at the unit test suite. Error handling -------------- -Proper error handling helps us identify bugs in our code, and helps end-users +Proper error handling helps us identify bugs in our code, and helps end users understand errors in their tool usage. Errors fall into two broad categories: *programmatic* and *recoverable*, with different strategies for handling and reporting. @@ -449,10 +449,10 @@ violations even in builds that do not enable assertions: Recoverable Errors ^^^^^^^^^^^^^^^^^^ -Recoverable errors represent an error in the program's environment, for example +Recoverable errors represent an error in the program's environment, for example, a resource failure (a missing file, a dropped network connection, etc.), or malformed input. These errors should be detected and communicated to a level of -the program where they can be handled appropriately. Handling the error may be +the program that can handle them appropriately. Handling the error may be as simple as reporting the issue to the user, or it may involve attempts at recovery. @@ -668,7 +668,7 @@ Since the list of handlers passed to ``handleErrors`` may not cover every error type that can occur, the ``handleErrors`` function also returns an Error value that must be checked or propagated. If the error value that is passed to ``handleErrors`` does not match any of the handlers it will be returned from -handleErrors. Idiomatic use of ``handleErrors`` thus looks like: +``handleErrors``. Idiomatic use of ``handleErrors`` thus looks like: .. code-block:: c++ @@ -683,18 +683,18 @@ handleErrors. Idiomatic use of ``handleErrors`` thus looks like: })) return Err; -In cases where you truly know that the handler list is exhaustive the +In cases where you truly know that the handler list is exhaustive, the ``handleAllErrors`` function can be used instead. This is identical to ``handleErrors`` except that it will terminate the program if an unhandled error is passed in, and can therefore return void. The ``handleAllErrors`` function should generally be avoided: the introduction of a new error type elsewhere in the program can easily turn a formerly exhaustive list of errors into a non-exhaustive list, risking unexpected program termination. Where -possible, use handleErrors and propagate unknown errors up the stack instead. +possible, use ``handleErrors`` and propagate unknown errors up the stack instead. For tool code, where errors can be handled by printing an error message then exiting with an error code, the :ref:`ExitOnError <err_exitonerr>` utility -may be a better choice than handleErrors, as it simplifies control flow when +may be a better choice than ``handleErrors``, as it simplifies control flow when calling fallible functions. In situations where it is known that a particular call to a fallible function @@ -706,9 +706,9 @@ simplifying control flow. StringError """"""""""" -Many kinds of errors have no recovery strategy, the only action that can be +Many kinds of errors have no recovery strategy; the only action that can be taken is to report them to the user so that the user can attempt to fix the -environment. In this case representing the error as a string makes perfect +environment. In this case, representing the error as a string makes perfect sense. LLVM provides the ``StringError`` class for this purpose. It takes two arguments: A string error message, and an equivalent ``std::error_code`` for interoperability. It also provides a ``createStringError`` function to simplify @@ -721,7 +721,7 @@ common usage of this class: createStringError(errc::executable_format_error, "Bad executable"); If you're certain that the error you're building will never need to be converted -to a ``std::error_code`` you can use the ``inconvertibleErrorCode()`` function: +to a ``std::error_code``, you can use the ``inconvertibleErrorCode()`` function: .. code-block:: c++ @@ -791,18 +791,18 @@ actually recognises three different forms of handler signature: Error(std::unique_ptr<UserDefinedError> E); Any error returned from a handler will be returned from the ``handleErrors`` -function so that it can be handled itself, or propagated up the stack. +function so that it can be handled itself or propagated up the stack. .. _err_exitonerr: Using ExitOnError to simplify tool code """"""""""""""""""""""""""""""""""""""" -Library code should never call ``exit`` for a recoverable error, however in tool +Library code should never call ``exit`` for a recoverable error; however, in tool code (especially command line tools) this can be a reasonable approach. Calling ``exit`` upon encountering an error dramatically simplifies control flow as the error no longer needs to be propagated up the stack. This allows code to be -written in straight-line style, as long as each fallible call is wrapped in a +written in a straight-line style, as long as each fallible call is wrapped in a check and call to exit. The ``ExitOnError`` class supports this pattern by providing call operators that inspect ``Error`` values, stripping the error away in the success case and logging to ``stderr`` then exiting in the failure case. @@ -827,7 +827,7 @@ turning them into non-failing calls: } On failure, the error's log message will be written to ``stderr``, optionally -preceded by a string "banner" that can be set by calling the setBanner method. A +preceded by a string "banner" that can be set by calling the ``setBanner`` method. A mapping can also be supplied from ``Error`` values to exit codes using the ``setExitCodeMapper`` method: @@ -854,8 +854,8 @@ Some functions may only fail for a subset of their inputs, so calls using known safe inputs can be assumed to succeed. The cantFail functions encapsulate this by wrapping an assertion that their -argument is a success value and, in the case of Expected<T>, unwrapping the -T value: +argument is a success value and, in the case of ``Expected<T>``, unwrapping the +``T`` value: .. code-block:: c++ @@ -868,16 +868,16 @@ T value: ... } -Like the ExitOnError utility, cantFail simplifies control flow. Their treatment +Like the ExitOnError utility, ``cantFail`` simplifies control flow. Their treatment of error cases is very different, however: Where ExitOnError is guaranteed to -terminate the program on an error input, cantFail simply asserts that the result +terminate the program on an error input, ``cantFail`` simply asserts that the result is success. In debug builds this will result in an assertion failure if an error -is encountered. In release builds, the behavior of cantFail for failure values is -undefined. As such, care must be taken in the use of cantFail: clients must be -certain that a cantFail wrapped call really can not fail with the given +is encountered. In release builds, the behavior of ``cantFail`` for failure values is +undefined. As such, care must be taken in the use of ``cantFail``: clients must be +certain that a ``cantFail`` wrapped call really can not fail with the given arguments. -Use of the cantFail functions should be rare in library code, but they are +Use of the ``cantFail`` functions should be rare in library code, but they are likely to be of more use in tool and unit-test code where inputs and/or mocked-up classes or functions may be known to be safe. @@ -979,7 +979,7 @@ completing the walk over the archive they could use the ``joinErrors`` utility: } The ``joinErrors`` routine builds a special error type called ``ErrorList``, -which holds a list of user defined errors. The ``handleErrors`` routine +which holds a list of user-defined errors. The ``handleErrors`` routine recognizes this type and will attempt to handle each of the contained errors in order. If all contained errors can be handled, ``handleErrors`` will return ``Error::success()``; otherwise, ``handleErrors`` will concatenate the remaining @@ -1146,7 +1146,7 @@ be passed by value. The ``LDBG`` and ``LLVM_DEBUG()`` macros and ``-debug`` option -------------------------------------------------------------- -Often when working on your pass you will put a bunch of debugging printouts and +Often, when working on your pass, you will put a bunch of debugging printouts and other code into your pass. After you get it working, you want to remove it, but you may need it again in the future (to work out new bugs that you run across). @@ -1183,7 +1183,7 @@ The debug output can be enabled by passing the ``-debug`` command line argument. $ opt < a.bc > /dev/null -mypass -debug [my-pass MyPass.cpp:123 2] I am here! -While `LDBG()` is useful to add debug output to your code, there are cases +While ``LDBG()`` is useful to add debug output to your code, there are cases where you may need to guard a block of code with a debug check. The ``llvm/Support/Debug.h`` (`doxygen <https://llvm.org/doxygen/Debug_8h_source.html>`__) file provides a macro named @@ -1220,7 +1220,7 @@ with ``-debug``. Fine grained debug info with ``DEBUG_TYPE`` and the ``-debug-only`` option ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Sometimes you may find yourself in a situation where enabling ``-debug`` just +Sometimes, you may find yourself in a situation where enabling ``-debug`` just turns on **too much** information (such as when working on the code generator). If you want to enable debug information with more fine-grained control, you can control the debug type and level with associate with each logging statement @@ -1389,7 +1389,7 @@ maintainable and useful. Adding debug counters to aid in debugging your code --------------------------------------------------- -Sometimes, when writing new passes, or trying to track down bugs, it +Sometimes, when writing new passes or trying to track down bugs, it is useful to be able to control whether certain things in your pass happen or not. For example, there are times the minimization tooling can only easily give you large testcases. You would like to narrow @@ -1729,17 +1729,17 @@ page and one extra indirection when accessing elements with their positional index. In order to minimise the memory footprint of this container, it's important to -balance the ``PageSize`` so that it's not too small (otherwise the overhead of the -pointer per page might become too high) and not too big (otherwise the memory +balance the ``PageSize`` so that it's not too small (otherwise, the overhead of the +pointer per page might become too high) and not too big (otherwise, the memory is wasted if the page is not fully used). Moreover, while retaining the order of the elements based on their insertion index, like a vector, iterating over the elements via ``begin()`` and ``end()`` -is not provided in the API, due to the fact accessing the elements in order +is not provided in the API, due to the fact that accessing the elements in order would allocate all the iterated pages, defeating memory savings and the purpose of the ``PagedVector``. -Finally a ``materialized_begin()`` and ``materialized_end`` iterators are +Finally, ``materialized_begin()`` and ``materialized_end`` iterators are provided to access the elements associated to the accessed pages, which could speed up operations that need to iterate over initialized elements in a non-ordered manner. @@ -1782,9 +1782,9 @@ loop. ^^^^^^^ ``std::deque`` is, in some senses, a generalized version of ``std::vector``. -Like ``std::vector``, it provides constant time random access and other similar +Like ``std::vector``, it provides constant-time random access and other similar properties, but it also provides efficient access to the front of the list. It -does not guarantee continuity of elements within memory. +does not guarantee the continuity of elements within memory. In exchange for this extra flexibility, ``std::deque`` has significantly higher constant factor costs than ``std::vector``. If possible, use ``std::vector`` or @@ -1843,7 +1843,7 @@ Related classes of interest are explained in the following subsections: llvm/ADT/PackedVector.h ^^^^^^^^^^^^^^^^^^^^^^^ -Useful for storing a vector of values using only a few number of bits for each +Useful for storing a vector of values using only a few bits for each value. Apart from the standard operations of a vector-like container, it can also perform an 'or' set operation. @@ -1901,13 +1901,13 @@ non-empty ``ilist``\ s. The only sensible solution to this problem is to allocate a so-called *sentinel* along with the intrusive list, which serves as the ``end`` iterator, providing -the back-link to the last element. However conforming to the C++ convention it +the back-link to the last element. However, conforming to the C++ convention it is illegal to ``operator++`` beyond the sentinel and it also must not be dereferenced. These constraints allow for some implementation freedom to the ``ilist`` how to allocate and store the sentinel. The corresponding policy is dictated by -``ilist_traits<T>``. By default a ``T`` gets heap-allocated whenever the need +``ilist_traits<T>``. By default, a ``T`` gets heap-allocated whenever the need for a sentinel arises. While the default policy is sufficient in most cases, it may break down when @@ -1941,7 +1941,7 @@ String-like containers There are a variety of ways to pass around and use strings in C and C++, and LLVM adds a few new options to choose from. Pick the first option on this list -that will do what you need, they are ordered according to their relative cost. +that will do what you need; they are ordered according to their relative cost. Note that it is generally preferred to *not* pass strings around as ``const char*``'s. These have a number of problems, including the fact that they @@ -1973,12 +1973,12 @@ either because they are C string literals, ``std::string``, a C array, or a ``StringRef`` has a few major limitations which make more powerful string containers useful: -#. You cannot directly convert a ``StringRef`` to a 'const char*' because there is +#. You cannot directly convert a ``StringRef`` to a ``const char*`` because there is no way to add a trailing nul (unlike the ``.c_str()`` method on various stronger classes). #. ``StringRef`` doesn't own or keep alive the underlying string bytes. - As such it can easily lead to dangling pointers, and is not suitable for + As such, it can easily lead to dangling pointers, and is not suitable for embedding in datastructures in most cases (instead, use an ``std::string`` or something like that). diff --git a/llvm/docs/ReleaseNotes.md b/llvm/docs/ReleaseNotes.md index 49158fb..bfe6827 100644 --- a/llvm/docs/ReleaseNotes.md +++ b/llvm/docs/ReleaseNotes.md @@ -180,6 +180,10 @@ Changes to the LLVM tools * Some code paths for supporting Python 2.7 in `llvm-lit` have been removed. * Support for `%T` in lit has been removed. +* `llvm-config` gained a new flag `--quote-paths` which quotes and escapes paths + emitted on stdout, to account for spaces or other special characters in path. + (`#97305 <https://github.com/llvm/llvm-project/pull/97305>`_). + Changes to LLDB --------------------------------- |