From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 1851) id 47A103858417; Tue, 8 Nov 2022 14:42:24 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 47A103858417 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1667918544; bh=8jpJoqBEpf77/6RIJdb9wSAwwzJuRCenE6KZi5xBSG4=; h=From:To:Subject:Date:From; b=gpT3kQUKZITJ1b8hWfcaWjf95gnLGmN/xcUTZJiPAVlAiZSOu26yNyVBHNnaQlVed BK3BvytWBzFN7oSD3J8vOQKQCTyzifU5emzh4dkWV0PtjdbxIHA8zkLArPJqdwh2eg 8k8GefHPnE87MUs9F9grb3u5ZBYIsTl+iXOWniAY= MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain; charset="utf-8" From: Martin Liska To: gcc-cvs@gcc.gnu.org Subject: [gcc(refs/users/marxin/heads/sphinx-final)] sphinx: copy files from texi2rst-generated repository X-Act-Checkin: gcc X-Git-Author: Martin Liska X-Git-Refname: refs/users/marxin/heads/sphinx-final X-Git-Oldrev: fa271afb58423014e2feef9f15c1a87428e64ddc X-Git-Newrev: 3af87c14b8363ae0f64a942cb6d31857b23ee767 Message-Id: <20221108144224.47A103858417@sourceware.org> Date: Tue, 8 Nov 2022 14:42:24 +0000 (GMT) List-Id: https://gcc.gnu.org/g:3af87c14b8363ae0f64a942cb6d31857b23ee767 commit 3af87c14b8363ae0f64a942cb6d31857b23ee767 Author: Martin Liska Date: Mon Nov 7 12:54:13 2022 +0100 sphinx: copy files from texi2rst-generated repository ChangeLog: * doc/Makefile: New file. * doc/_static/custom.css: New file. * doc/baseconf.py: New file. * doc/bsd.rst: New file. * doc/contrib.rst: New file. * doc/contribute.rst: New file. * doc/cppdiropts.rst: New file. * doc/cppenv.rst: New file. * doc/cppopts.rst: New file. * doc/cppwarnopts.rst: New file. * doc/favicon.ico: New file. * doc/funding.rst: New file. * doc/gcc_sphinx.py: New file. * doc/gnu.rst: New file. * doc/gnu_free_documentation_license.rst: New file. * doc/gpl-3.0.rst: New file. * doc/indices-and-tables.rst: New file. * doc/lgpl-2.1.rst: New file. * doc/logo.pdf: New file. * doc/logo.svg: New file. * doc/md.rst: New file. * doc/requirements.txt: New file. gcc/d/ChangeLog: * doc/conf.py: New file. * doc/copyright.rst: New file. * doc/general-public-license-3.rst: New file. * doc/gnu-free-documentation-license.rst: New file. * doc/index.rst: New file. * doc/indices-and-tables.rst: New file. * doc/invoking-gdc.rst: New file. * doc/invoking-gdc/code-generation.rst: New file. * doc/invoking-gdc/developer-options.rst: New file. * doc/invoking-gdc/input-and-output-files.rst: New file. * doc/invoking-gdc/options-for-directory-search.rst: New file. * doc/invoking-gdc/options-for-linking.rst: New file. * doc/invoking-gdc/runtime-options.rst: New file. * doc/invoking-gdc/warnings.rst: New file. gcc/ChangeLog: * doc/cpp/character-sets.rst: New file. * doc/cpp/conditional-syntax.rst: New file. * doc/cpp/conditional-uses.rst: New file. * doc/cpp/conditionals.rst: New file. * doc/cpp/conf.py: New file. * doc/cpp/copyright.rst: New file. * doc/cpp/deleted-code.rst: New file. * doc/cpp/diagnostics.rst: New file. * doc/cpp/environment-variables.rst: New file. * doc/cpp/gnu-free-documentation-license.rst: New file. * doc/cpp/header-files.rst: New file. * doc/cpp/header-files/alternatives-to-wrapper-ifndef.rst: New file. * doc/cpp/header-files/computed-includes.rst: New file. * doc/cpp/header-files/include-operation.rst: New file. * doc/cpp/header-files/include-syntax.rst: New file. * doc/cpp/header-files/once-only-headers.rst: New file. * doc/cpp/header-files/search-path.rst: New file. * doc/cpp/header-files/system-headers.rst: New file. * doc/cpp/header-files/wrapper-headers.rst: New file. * doc/cpp/implementation-defined-behavior.rst: New file. * doc/cpp/implementation-details.rst: New file. * doc/cpp/implementation-limits.rst: New file. * doc/cpp/index.rst: New file. * doc/cpp/indices-and-tables.rst: New file. * doc/cpp/initial-processing.rst: New file. * doc/cpp/invocation.rst: New file. * doc/cpp/line-control.rst: New file. * doc/cpp/macros.rst: New file. * doc/cpp/macros/concatenation.rst: New file. * doc/cpp/macros/directives-within-macro-arguments.rst: New file. * doc/cpp/macros/function-like-macros.rst: New file. * doc/cpp/macros/macro-arguments.rst: New file. * doc/cpp/macros/macro-pitfalls.rst: New file. * doc/cpp/macros/object-like-macros.rst: New file. * doc/cpp/macros/predefined-macros.rst: New file. * doc/cpp/macros/stringizing.rst: New file. * doc/cpp/macros/undefining-and-redefining-macros.rst: New file. * doc/cpp/macros/variadic-macros.rst: New file. * doc/cpp/obsolete-features.rst: New file. * doc/cpp/other-directives.rst: New file. * doc/cpp/overview.rst: New file. * doc/cpp/pragmas.rst: New file. * doc/cpp/preprocessor-output.rst: New file. * doc/cpp/the-preprocessing-language.rst: New file. * doc/cpp/tokenization.rst: New file. * doc/cpp/traditional-lexical-analysis.rst: New file. * doc/cpp/traditional-macros.rst: New file. * doc/cpp/traditional-miscellany.rst: New file. * doc/cpp/traditional-mode.rst: New file. * doc/cpp/traditional-warnings.rst: New file. * doc/cppinternals/conf.py: New file. * doc/cppinternals/copyright.rst: New file. * doc/cppinternals/cppinternals.rst: New file. * doc/cppinternals/cpplib.rst: New file. * doc/cppinternals/files.rst: New file. * doc/cppinternals/index.rst: New file. * doc/cppinternals/indices-and-tables.rst: New file. * doc/cppinternals/internal-representation-of-macros.rst: New file. * doc/cppinternals/just-which-line-number-anyway.rst: New file. * doc/cppinternals/lexing-a-line.rst: New file. * doc/cppinternals/lexing-a-token.rst: New file. * doc/cppinternals/looking-for-a-function-like-macros-opening-parenthesis.rst: New file. * doc/cppinternals/macro-expansion-overview.rst: New file. * doc/cppinternals/marking-tokens-ineligible-for-future-expansion.rst: New file. * doc/cppinternals/multiple-include-optimization.rst: New file. * doc/cppinternals/overview.rst: New file. * doc/cppinternals/representation-of-line-numbers.rst: New file. * doc/cppinternals/scanning-the-replacement-list-for-macros-to-expand.rst: New file. * doc/gcc/binary-compatibility.rst: New file. * doc/gcc/c++-implementation-defined-behavior.rst: New file. * doc/gcc/c-implementation-defined-behavior.rst: New file. * doc/gcc/c-implementation-defined-behavior/architecture.rst: New file. * doc/gcc/c-implementation-defined-behavior/arrays-and-pointers.rst: New file. * doc/gcc/c-implementation-defined-behavior/characters.rst: New file. * doc/gcc/c-implementation-defined-behavior/declarators.rst: New file. * doc/gcc/c-implementation-defined-behavior/environment.rst: New file. * doc/gcc/c-implementation-defined-behavior/floating-point.rst: New file. * doc/gcc/c-implementation-defined-behavior/hints.rst: New file. * doc/gcc/c-implementation-defined-behavior/identifiers.rst: New file. * doc/gcc/c-implementation-defined-behavior/integers.rst: New file. * doc/gcc/c-implementation-defined-behavior/library-functions.rst: New file. * doc/gcc/c-implementation-defined-behavior/locale-specific-behavior.rst: New file. * doc/gcc/c-implementation-defined-behavior/preprocessing-directives.rst: New file. * doc/gcc/c-implementation-defined-behavior/qualifiers.rst: New file. * doc/gcc/c-implementation-defined-behavior/statements.rst: New file. * doc/gcc/c-implementation-defined-behavior/structures-unions-enumerations-and-bit-fields.rst: New file. * doc/gcc/c-implementation-defined-behavior/translation.rst: New file. * doc/gcc/conditionally-supported-behavior.rst: New file. * doc/gcc/conf.py: New file. * doc/gcc/contributing-to-gcc-development.rst: New file. * doc/gcc/contributors-to-gcc.rst: New file. * doc/gcc/copyright.rst: New file. * doc/gcc/exception-handling.rst: New file. * doc/gcc/extensions-to-the-c++-language.rst: New file. * doc/gcc/extensions-to-the-c++-language/backwards-compatibility.rst: New file. * doc/gcc/extensions-to-the-c++-language/c++-concepts.rst: New file. * doc/gcc/extensions-to-the-c++-language/c++-interface-and-implementation-pragmas.rst: New file. * doc/gcc/extensions-to-the-c++-language/c++-specific-variable-function-and-type-attributes.rst: New file. * doc/gcc/extensions-to-the-c++-language/deprecated-features.rst: New file. * doc/gcc/extensions-to-the-c++-language/extracting-the-function-pointer-from-a-bound-pointer-to-member-function.rst: New file. * doc/gcc/extensions-to-the-c++-language/function-multiversioning.rst: New file. * doc/gcc/extensions-to-the-c++-language/restricting-pointer-aliasing.rst: New file. * doc/gcc/extensions-to-the-c++-language/type-traits.rst: New file. * doc/gcc/extensions-to-the-c++-language/vague-linkage.rst: New file. * doc/gcc/extensions-to-the-c++-language/when-is-a-volatile-c++-object-accessed.rst: New file. * doc/gcc/extensions-to-the-c++-language/wheres-the-template.rst: New file. * doc/gcc/extensions-to-the-c-language-family.rst: New file. * doc/gcc/extensions-to-the-c-language-family/128-bit-integers.rst: New file. * doc/gcc/extensions-to-the-c-language-family/additional-floating-types.rst: New file. * doc/gcc/extensions-to-the-c-language-family/alternate-keywords.rst: New file. * doc/gcc/extensions-to-the-c-language-family/an-inline-function-is-as-fast-as-a-macro.rst: New file. * doc/gcc/extensions-to-the-c-language-family/arithmetic-on-void-and-function-pointers.rst: New file. * doc/gcc/extensions-to-the-c-language-family/arrays-of-length-zero.rst: New file. * doc/gcc/extensions-to-the-c-language-family/arrays-of-variable-length.rst: New file. * doc/gcc/extensions-to-the-c-language-family/attribute-syntax.rst: New file. * doc/gcc/extensions-to-the-c-language-family/binary-constants-using-the-0b-prefix.rst: New file. * doc/gcc/extensions-to-the-c-language-family/built-in-functions-for-memory-model-aware-atomic-operations.rst: New file. * doc/gcc/extensions-to-the-c-language-family/built-in-functions-to-perform-arithmetic-with-overflow-checking.rst: New file. * doc/gcc/extensions-to-the-c-language-family/c++-style-comments.rst: New file. * doc/gcc/extensions-to-the-c-language-family/case-ranges.rst: New file. * doc/gcc/extensions-to-the-c-language-family/cast-to-a-union-type.rst: New file. * doc/gcc/extensions-to-the-c-language-family/complex-numbers.rst: New file. * doc/gcc/extensions-to-the-c-language-family/compound-literals.rst: New file. * doc/gcc/extensions-to-the-c-language-family/conditionals-with-omitted-operands.rst: New file. * doc/gcc/extensions-to-the-c-language-family/constructing-function-calls.rst: New file. * doc/gcc/extensions-to-the-c-language-family/decimal-floating-types.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/aarch64-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/amd-gcn-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/arc-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/arm-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/avr-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/blackfin-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/bpf-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/c-sky-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/common-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/epiphany-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/h8-300-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/ia-64-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/m32c-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/m32r-d-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/m68k-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/mcore-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/mep-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/microblaze-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/microsoft-windows-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/mips-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/msp430-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/nds32-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/nios-ii-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/nvidia-ptx-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/powerpc-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/risc-v-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/rl78-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/rx-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/s-390-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/sh-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/symbian-os-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/v850-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/visium-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/x86-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/xstormy16-function-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/designated-initializers.rst: New file. * doc/gcc/extensions-to-the-c-language-family/determining-the-alignment-of-functions-types-or-variables.rst: New file. * doc/gcc/extensions-to-the-c-language-family/dollar-signs-in-identifier-names.rst: New file. * doc/gcc/extensions-to-the-c-language-family/double-word-integers.rst: New file. * doc/gcc/extensions-to-the-c-language-family/enumerator-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/fixed-point-types.rst: New file. * doc/gcc/extensions-to-the-c-language-family/format-checks-specific-to-particular-target-machines.rst: New file. * doc/gcc/extensions-to-the-c-language-family/function-names-as-strings.rst: New file. * doc/gcc/extensions-to-the-c-language-family/getting-the-return-or-frame-address-of-a-function.rst: New file. * doc/gcc/extensions-to-the-c-language-family/half-precision-floating-point.rst: New file. * doc/gcc/extensions-to-the-c-language-family/hex-floats.rst: New file. * doc/gcc/extensions-to-the-c-language-family/how-to-use-inline-assembly-language-in-c-code.rst: New file. * doc/gcc/extensions-to-the-c-language-family/incomplete-enum-types.rst: New file. * doc/gcc/extensions-to-the-c-language-family/label-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/labels-as-values.rst: New file. * doc/gcc/extensions-to-the-c-language-family/legacy-sync-built-in-functions-for-atomic-memory-access.rst: New file. * doc/gcc/extensions-to-the-c-language-family/locally-declared-labels.rst: New file. * doc/gcc/extensions-to-the-c-language-family/macros-with-a-variable-number-of-arguments.rst: New file. * doc/gcc/extensions-to-the-c-language-family/mixed-declarations-labels-and-code.rst: New file. * doc/gcc/extensions-to-the-c-language-family/named-address-spaces.rst: New file. * doc/gcc/extensions-to-the-c-language-family/nested-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/non-constant-initializers.rst: New file. * doc/gcc/extensions-to-the-c-language-family/non-lvalue-arrays-may-have-subscripts.rst: New file. * doc/gcc/extensions-to-the-c-language-family/nonlocal-gotos.rst: New file. * doc/gcc/extensions-to-the-c-language-family/object-size-checking-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/other-built-in-functions-provided-by-gcc.rst: New file. * doc/gcc/extensions-to-the-c-language-family/pointer-arguments-in-variadic-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/pointers-to-arrays-with-qualifiers-work-as-expected.rst: New file. * doc/gcc/extensions-to-the-c-language-family/pragmas-accepted-by-gcc.rst: New file. * doc/gcc/extensions-to-the-c-language-family/prototypes-and-old-style-function-definitions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/referring-to-a-type-with-typeof.rst: New file. * doc/gcc/extensions-to-the-c-language-family/slightly-looser-rules-for-escaped-newlines.rst: New file. * doc/gcc/extensions-to-the-c-language-family/specifying-attributes-of-types.rst: New file. * doc/gcc/extensions-to-the-c-language-family/specifying-attributes-of-variables.rst: New file. * doc/gcc/extensions-to-the-c-language-family/statement-attributes.rst: New file. * doc/gcc/extensions-to-the-c-language-family/statements-and-declarations-in-expressions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/structures-with-no-members.rst: New file. * doc/gcc/extensions-to-the-c-language-family/support-for-offsetof.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/aarch64-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/alpha-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/altera-nios-ii-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/arc-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/arc-simd-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/arm-armv8-m-security-extensions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/arm-c-language-extensions-acle.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/arm-floating-point-status-and-control-intrinsics.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/arm-iwmmxt-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/avr-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/basic-powerpc-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/blackfin-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/bpf-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/fr-v-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/mips-dsp-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/mips-loongson-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/mips-paired-single-support.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/mips-simd-architecture-msa-support.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/msp430-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/nds32-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/other-mips-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/picochip-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/powerpc-altivec-vsx-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/powerpc-atomic-memory-operation-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/powerpc-hardware-transactional-memory-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/powerpc-matrix-multiply-assist-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/pru-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/risc-v-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/rx-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/s-390-system-z-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/sh-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/sparc-vis-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/ti-c6x-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/x86-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/x86-control-flow-protection-intrinsics.rst: New file. * doc/gcc/extensions-to-the-c-language-family/target-builtins/x86-transactional-memory-intrinsics.rst: New file. * doc/gcc/extensions-to-the-c-language-family/the-character-esc-in-constants.rst: New file. * doc/gcc/extensions-to-the-c-language-family/thread-local-storage.rst: New file. * doc/gcc/extensions-to-the-c-language-family/unnamed-structure-and-union-fields.rst: New file. * doc/gcc/extensions-to-the-c-language-family/using-vector-instructions-through-built-in-functions.rst: New file. * doc/gcc/extensions-to-the-c-language-family/when-is-a-volatile-object-accessed.rst: New file. * doc/gcc/extensions-to-the-c-language-family/x86-specific-memory-model-extensions-for-transactional-memory.rst: New file. * doc/gcc/funding.rst: New file. * doc/gcc/gcc-command-options.rst: New file. * doc/gcc/gcc-command-options/c++-modules.rst: New file. * doc/gcc/gcc-command-options/compiling-c++-programs.rst: New file. * doc/gcc/gcc-command-options/description.rst: New file. * doc/gcc/gcc-command-options/environment-variables-affecting-gcc.rst: New file. * doc/gcc/gcc-command-options/gcc-developer-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/aarch64-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/adapteva-epiphany-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/amd-gcn-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/arc-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/arm-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/avr-mmcu.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/avr-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/blackfin-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/c-sky-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/c6x-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/cris-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/darwin-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/dec-alpha-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/ebpf-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/fr30-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/frv-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/ft32-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/gnu-linux-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/h8-300-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/hppa-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/ia-64-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/ibm-rs-6000-and-powerpc-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/lm32-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/loongarch-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/m32c-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/m32r-d-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/m680x0-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/mcore-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/mep-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/microblaze-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/mips-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/mmix-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/mn10300-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/moxie-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/msp430-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/nds32-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/nios-ii-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/nvidia-ptx-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/openrisc-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/options-for-system-v.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/pdp-11-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/picochip-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/powerpc-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/pru-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/risc-v-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/rl78-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/rx-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/s-390-and-zseries-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/score-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/sh-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/solaris-2-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/sparc-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/v850-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/vax-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/visium-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/vms-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/vxworks-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/x86-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/x86-windows-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/xstormy16-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/xtensa-options.rst: New file. * doc/gcc/gcc-command-options/machine-dependent-options/zseries-options.rst: New file. * doc/gcc/gcc-command-options/option-summary.rst: New file. * doc/gcc/gcc-command-options/options-controlling-c++-dialect.rst: New file. * doc/gcc/gcc-command-options/options-controlling-c-dialect.rst: New file. * doc/gcc/gcc-command-options/options-controlling-objective-c-and-objective-c++-dialects.rst: New file. * doc/gcc/gcc-command-options/options-controlling-the-kind-of-output.rst: New file. * doc/gcc/gcc-command-options/options-controlling-the-preprocessor.rst: New file. * doc/gcc/gcc-command-options/options-for-code-generation-conventions.rst: New file. * doc/gcc/gcc-command-options/options-for-debugging-your-program.rst: New file. * doc/gcc/gcc-command-options/options-for-directory-search.rst: New file. * doc/gcc/gcc-command-options/options-for-linking.rst: New file. * doc/gcc/gcc-command-options/options-that-control-optimization.rst: New file. * doc/gcc/gcc-command-options/options-that-control-static-analysis.rst: New file. * doc/gcc/gcc-command-options/options-to-control-diagnostic-messages-formatting.rst: New file. * doc/gcc/gcc-command-options/options-to-request-or-suppress-warnings.rst: New file. * doc/gcc/gcc-command-options/passing-options-to-the-assembler.rst: New file. * doc/gcc/gcc-command-options/program-instrumentation-options.rst: New file. * doc/gcc/gcc-command-options/specifying-subprocesses-and-the-switches-to-pass-to-them.rst: New file. * doc/gcc/gcc-command-options/using-precompiled-headers.rst: New file. * doc/gcc/gcc.rst: New file. * doc/gcc/gcov-dump.rst: New file. * doc/gcc/gcov-tool.rst: New file. * doc/gcc/gcov.rst: New file. * doc/gcc/gcov/brief-description-of-gcov-data-files.rst: New file. * doc/gcc/gcov/data-file-relocation-to-support-cross-profiling.rst: New file. * doc/gcc/gcov/introduction-to-gcov.rst: New file. * doc/gcc/gcov/invoking-gcov.rst: New file. * doc/gcc/gcov/profiling-and-test-coverage-in-freestanding-environments.rst: New file. * doc/gcc/gcov/using-gcov-with-gcc-optimization.rst: New file. * doc/gcc/general-public-license-3.rst: New file. * doc/gcc/gnu-free-documentation-license.rst: New file. * doc/gcc/gnu-objective-c-features.rst: New file. * doc/gcc/gnu-objective-c-features/compatibilityalias.rst: New file. * doc/gcc/gnu-objective-c-features/constant-string-objects.rst: New file. * doc/gcc/gnu-objective-c-features/exceptions.rst: New file. * doc/gcc/gnu-objective-c-features/fast-enumeration.rst: New file. * doc/gcc/gnu-objective-c-features/garbage-collection.rst: New file. * doc/gcc/gnu-objective-c-features/gnu-objective-c-runtime-api.rst: New file. * doc/gcc/gnu-objective-c-features/load-executing-code-before-main.rst: New file. * doc/gcc/gnu-objective-c-features/messaging-with-the-gnu-objective-c-runtime.rst: New file. * doc/gcc/gnu-objective-c-features/synchronization.rst: New file. * doc/gcc/gnu-objective-c-features/type-encoding.rst: New file. * doc/gcc/gnu.rst: New file. * doc/gcc/have-you-found-a-bug.rst: New file. * doc/gcc/how-and-where-to-report-bugs.rst: New file. * doc/gcc/how-to-get-help-with-gcc.rst: New file. * doc/gcc/index.rst: New file. * doc/gcc/indices-and-tables.rst: New file. * doc/gcc/known-causes-of-trouble-with-gcc.rst: New file. * doc/gcc/known-causes-of-trouble-with-gcc/actual-bugs-we-havent-fixed-yet.rst: New file. * doc/gcc/known-causes-of-trouble-with-gcc/certain-changes-we-dont-want-to-make.rst: New file. * doc/gcc/known-causes-of-trouble-with-gcc/common-misunderstandings-with-gnu-c.rst: New file. * doc/gcc/known-causes-of-trouble-with-gcc/disappointments-and-misunderstandings.rst: New file. * doc/gcc/known-causes-of-trouble-with-gcc/fixed-header-files.rst: New file. * doc/gcc/known-causes-of-trouble-with-gcc/incompatibilities-of-gcc.rst: New file. * doc/gcc/known-causes-of-trouble-with-gcc/interoperation.rst: New file. * doc/gcc/known-causes-of-trouble-with-gcc/standard-libraries.rst: New file. * doc/gcc/known-causes-of-trouble-with-gcc/warning-messages-and-error-messages.rst: New file. * doc/gcc/language-standards-supported-by-gcc.rst: New file. * doc/gcc/language-standards-supported-by-gcc/c++-language.rst: New file. * doc/gcc/language-standards-supported-by-gcc/c-language.rst: New file. * doc/gcc/language-standards-supported-by-gcc/d-language.rst: New file. * doc/gcc/language-standards-supported-by-gcc/go-language.rst: New file. * doc/gcc/language-standards-supported-by-gcc/objective-c-and-objective-c++-languages.rst: New file. * doc/gcc/language-standards-supported-by-gcc/references-for-other-languages.rst: New file. * doc/gcc/lto-dump.rst: New file. * doc/gcc/programming-languages-supported-by-gcc.rst: New file. * doc/gcc/reporting-bugs.rst: New file. * doc/gccint/analysis-and-optimization-of-gimple-tuples.rst: New file. * doc/gccint/analysis-and-optimization-of-gimple-tuples/alias-analysis.rst: New file. * doc/gccint/analysis-and-optimization-of-gimple-tuples/annotations.rst: New file. * doc/gccint/analysis-and-optimization-of-gimple-tuples/memory-model.rst: New file. * doc/gccint/analysis-and-optimization-of-gimple-tuples/ssa-operands.rst: New file. * doc/gccint/analysis-and-optimization-of-gimple-tuples/static-single-assignment.rst: New file. * doc/gccint/analysis-and-representation-of-loops.rst: New file. * doc/gccint/analysis-and-representation-of-loops/data-dependency-analysis.rst: New file. * doc/gccint/analysis-and-representation-of-loops/iv-analysis-on-rtl.rst: New file. * doc/gccint/analysis-and-representation-of-loops/loop-closed-ssa-form.rst: New file. * doc/gccint/analysis-and-representation-of-loops/loop-manipulation.rst: New file. * doc/gccint/analysis-and-representation-of-loops/loop-querying.rst: New file. * doc/gccint/analysis-and-representation-of-loops/loop-representation.rst: New file. * doc/gccint/analysis-and-representation-of-loops/number-of-iterations-analysis.rst: New file. * doc/gccint/analysis-and-representation-of-loops/scalar-evolutions.rst: New file. * doc/gccint/analyzer-internals.rst: New file. * doc/gccint/collect2.rst: New file. * doc/gccint/conf.py: New file. * doc/gccint/contributing-to-gcc-development.rst: New file. * doc/gccint/contributors-to-gcc.rst: New file. * doc/gccint/control-flow-graph.rst: New file. * doc/gccint/control-flow-graph/basic-blocks.rst: New file. * doc/gccint/control-flow-graph/edges.rst: New file. * doc/gccint/control-flow-graph/liveness-information.rst: New file. * doc/gccint/control-flow-graph/maintaining-the-cfg.rst: New file. * doc/gccint/control-flow-graph/profile-information.rst: New file. * doc/gccint/copyright.rst: New file. * doc/gccint/debugging-the-analyzer.rst: New file. * doc/gccint/funding.rst: New file. * doc/gccint/gcc-and-portability.rst: New file. * doc/gccint/general-public-license-3.rst: New file. * doc/gccint/generic.rst: New file. * doc/gccint/generic/attributes-in-trees.rst: New file. * doc/gccint/generic/c-and-c++-trees.rst: New file. * doc/gccint/generic/declarations.rst: New file. * doc/gccint/generic/deficiencies.rst: New file. * doc/gccint/generic/expressions.rst: New file. * doc/gccint/generic/functions.rst: New file. * doc/gccint/generic/language-dependent-trees.rst: New file. * doc/gccint/generic/overview.rst: New file. * doc/gccint/generic/statements.rst: New file. * doc/gccint/generic/types.rst: New file. * doc/gccint/gimple-api.rst: New file. * doc/gccint/gimple.rst: New file. * doc/gccint/gimple/adding-a-new-gimple-statement-code.rst: New file. * doc/gccint/gimple/class-hierarchy-of-gimple-statements.rst: New file. * doc/gccint/gimple/exception-handling.rst: New file. * doc/gccint/gimple/gimple-instruction-set.rst: New file. * doc/gccint/gimple/gimple-sequences.rst: New file. * doc/gccint/gimple/manipulating-gimple-statements.rst: New file. * doc/gccint/gimple/operands.rst: New file. * doc/gccint/gimple/sequence-iterators.rst: New file. * doc/gccint/gimple/statement-and-operand-traversals.rst: New file. * doc/gccint/gimple/temporaries.rst: New file. * doc/gccint/gimple/tuple-representation.rst: New file. * doc/gccint/gimple/tuple-specific-accessors.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpleasm.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpleassign.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimplebind.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimplecall.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimplecatch.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimplecond.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpledebug.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpleehfilter.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimplegoto.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimplelabel.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimplenop.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpleompatomicload.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpleompatomicstore.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpleompcontinue.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpleompcritical.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpleompfor.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpleompmaster.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpleompordered.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpleompparallel.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpleompreturn.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpleompsection.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpleompsections.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpleompsingle.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimplephi.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpleresx.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimplereturn.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpleswitch.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimpletry.rst: New file. * doc/gccint/gimple/tuple-specific-accessors/gimplewithcleanupexpr.rst: New file. * doc/gccint/gnu-free-documentation-license.rst: New file. * doc/gccint/guidelines-for-diagnostics.rst: New file. * doc/gccint/guidelines-for-options.rst: New file. * doc/gccint/host-common.rst: New file. * doc/gccint/host-configuration.rst: New file. * doc/gccint/host-filesystem.rst: New file. * doc/gccint/host-makefile-fragments.rst: New file. * doc/gccint/host-misc.rst: New file. * doc/gccint/index.rst: New file. * doc/gccint/indices-and-tables.rst: New file. * doc/gccint/interfacing-to-gcc-output.rst: New file. * doc/gccint/introduction.rst: New file. * doc/gccint/language-front-ends-in-gcc.rst: New file. * doc/gccint/link-time-optimization.rst: New file. * doc/gccint/link-time-optimization/design-overview.rst: New file. * doc/gccint/link-time-optimization/internal-flags-controlling-lto1.rst: New file. * doc/gccint/link-time-optimization/lto-file-sections.rst: New file. * doc/gccint/link-time-optimization/using-summary-information-in-ipa-passes.rst: New file. * doc/gccint/link-time-optimization/whole-program-assumptions-linker-plugin-and-symbol-visibilities.rst: New file. * doc/gccint/machine-descriptions.rst: New file. * doc/gccint/machine-descriptions/c-statements-for-assembler-output.rst: New file. * doc/gccint/machine-descriptions/canonicalization-of-instructions.rst: New file. * doc/gccint/machine-descriptions/conditional-execution.rst: New file. * doc/gccint/machine-descriptions/constant-definitions.rst: New file. * doc/gccint/machine-descriptions/defining-how-to-split-instructions.rst: New file. * doc/gccint/machine-descriptions/defining-jump-instruction-patterns.rst: New file. * doc/gccint/machine-descriptions/defining-looping-instruction-patterns.rst: New file. * doc/gccint/machine-descriptions/defining-rtl-sequences-for-code-generation.rst: New file. * doc/gccint/machine-descriptions/everything-about-instruction-patterns.rst: New file. * doc/gccint/machine-descriptions/example-of-defineinsn.rst: New file. * doc/gccint/machine-descriptions/including-patterns-in-machine-descriptions.rst: New file. * doc/gccint/machine-descriptions/instruction-attributes.rst: New file. * doc/gccint/machine-descriptions/interdependence-of-patterns.rst: New file. * doc/gccint/machine-descriptions/iterators.rst: New file. * doc/gccint/machine-descriptions/machine-specific-peephole-optimizers.rst: New file. * doc/gccint/machine-descriptions/operand-constraints.rst: New file. * doc/gccint/machine-descriptions/output-templates-and-operand-substitution.rst: New file. * doc/gccint/machine-descriptions/overview-of-how-the-machine-description-is-used.rst: New file. * doc/gccint/machine-descriptions/predicates.rst: New file. * doc/gccint/machine-descriptions/rtl-template.rst: New file. * doc/gccint/machine-descriptions/rtl-templates-transformations.rst: New file. * doc/gccint/machine-descriptions/standard-pattern-names-for-generation.rst: New file. * doc/gccint/machine-descriptions/when-the-order-of-patterns-matters.rst: New file. * doc/gccint/makefile-fragments.rst: New file. * doc/gccint/match-and-simplify.rst: New file. * doc/gccint/memory-management-and-type-information.rst: New file. * doc/gccint/memory-management-and-type-information/how-to-invoke-the-garbage-collector.rst: New file. * doc/gccint/memory-management-and-type-information/marking-roots-for-the-garbage-collector.rst: New file. * doc/gccint/memory-management-and-type-information/source-files-containing-type-information.rst: New file. * doc/gccint/memory-management-and-type-information/support-for-inheritance.rst: New file. * doc/gccint/memory-management-and-type-information/support-for-user-provided-gc-marking-routines.rst: New file. * doc/gccint/memory-management-and-type-information/the-inside-of-a-gty.rst: New file. * doc/gccint/memory-management-and-type-information/troubleshooting-the-garbage-collector.rst: New file. * doc/gccint/option-file-format.rst: New file. * doc/gccint/option-properties.rst: New file. * doc/gccint/option-specification-files.rst: New file. * doc/gccint/passes-and-files-of-the-compiler.rst: New file. * doc/gccint/passes-and-files-of-the-compiler/gimplification-pass.rst: New file. * doc/gccint/passes-and-files-of-the-compiler/inter-procedural-optimization-passes.rst: New file. * doc/gccint/passes-and-files-of-the-compiler/optimization-info.rst: New file. * doc/gccint/passes-and-files-of-the-compiler/parsing-pass.rst: New file. * doc/gccint/passes-and-files-of-the-compiler/pass-manager.rst: New file. * doc/gccint/passes-and-files-of-the-compiler/rtl-passes.rst: New file. * doc/gccint/passes-and-files-of-the-compiler/tree-ssa-passes.rst: New file. * doc/gccint/plugins.rst: New file. * doc/gccint/plugins/building-gcc-plugins.rst: New file. * doc/gccint/plugins/controlling-which-passes-are-being-run.rst: New file. * doc/gccint/plugins/giving-information-about-a-plugin.rst: New file. * doc/gccint/plugins/interacting-with-the-gcc-garbage-collector.rst: New file. * doc/gccint/plugins/interacting-with-the-pass-manager.rst: New file. * doc/gccint/plugins/keeping-track-of-available-passes.rst: New file. * doc/gccint/plugins/loading-plugins.rst: New file. * doc/gccint/plugins/plugin-api.rst: New file. * doc/gccint/plugins/recording-information-about-pass-execution.rst: New file. * doc/gccint/plugins/registering-custom-attributes-or-pragmas.rst: New file. * doc/gccint/rtl-representation.rst: New file. * doc/gccint/rtl-representation/access-to-operands.rst: New file. * doc/gccint/rtl-representation/access-to-special-operands.rst: New file. * doc/gccint/rtl-representation/assembler-instructions-as-expressions.rst: New file. * doc/gccint/rtl-representation/bit-fields.rst: New file. * doc/gccint/rtl-representation/comparison-operations.rst: New file. * doc/gccint/rtl-representation/constant-expression-types.rst: New file. * doc/gccint/rtl-representation/conversions.rst: New file. * doc/gccint/rtl-representation/declarations.rst: New file. * doc/gccint/rtl-representation/embedded-side-effects-on-addresses.rst: New file. * doc/gccint/rtl-representation/flags-in-an-rtl-expression.rst: New file. * doc/gccint/rtl-representation/insns.rst: New file. * doc/gccint/rtl-representation/machine-modes.rst: New file. * doc/gccint/rtl-representation/on-the-side-ssa-form-for-rtl.rst: New file. * doc/gccint/rtl-representation/reading-rtl.rst: New file. * doc/gccint/rtl-representation/registers-and-memory.rst: New file. * doc/gccint/rtl-representation/rtl-classes-and-formats.rst: New file. * doc/gccint/rtl-representation/rtl-expressions-for-arithmetic.rst: New file. * doc/gccint/rtl-representation/rtl-object-types.rst: New file. * doc/gccint/rtl-representation/rtl-representation-of-function-call-insns.rst: New file. * doc/gccint/rtl-representation/side-effect-expressions.rst: New file. * doc/gccint/rtl-representation/structure-sharing-assumptions.rst: New file. * doc/gccint/rtl-representation/variable-location-debug-information-in-rtl.rst: New file. * doc/gccint/rtl-representation/vector-operations.rst: New file. * doc/gccint/sizes-and-offsets-as-runtime-invariants.rst: New file. * doc/gccint/sizes-and-offsets-as-runtime-invariants/alignment-of-polyints.rst: New file. * doc/gccint/sizes-and-offsets-as-runtime-invariants/arithmetic-on-polyints.rst: New file. * doc/gccint/sizes-and-offsets-as-runtime-invariants/comparisons-involving-polyint.rst: New file. * doc/gccint/sizes-and-offsets-as-runtime-invariants/computing-bounds-on-polyints.rst: New file. * doc/gccint/sizes-and-offsets-as-runtime-invariants/consequences-of-using-polyint.rst: New file. * doc/gccint/sizes-and-offsets-as-runtime-invariants/converting-polyints.rst: New file. * doc/gccint/sizes-and-offsets-as-runtime-invariants/guidelines-for-using-polyint.rst: New file. * doc/gccint/sizes-and-offsets-as-runtime-invariants/miscellaneous-polyint-routines.rst: New file. * doc/gccint/sizes-and-offsets-as-runtime-invariants/overview-of-polyint.rst: New file. * doc/gccint/source-tree-structure-and-build-system.rst: New file. * doc/gccint/source-tree-structure-and-build-system/configure-terms-and-history.rst: New file. * doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory.rst: New file. * doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/anatomy-of-a-language-front-end.rst: New file. * doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/anatomy-of-a-target-back-end.rst: New file. * doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/build-system-in-the-gcc-directory.rst: New file. * doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/building-documentation.rst: New file. * doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/configuration-in-the-gcc-directory.rst: New file. * doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/headers-installed-by-gcc.rst: New file. * doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/library-source-files-and-headers-under-the-gcc-directory.rst: New file. * doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/makefile-targets.rst: New file. * doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/subdirectories-of-gcc.rst: New file. * doc/gccint/source-tree-structure-and-build-system/top-level-source-directory.rst: New file. * doc/gccint/standard-header-file-directories.rst: New file. * doc/gccint/static-analyzer.rst: New file. * doc/gccint/target-macros.rst: New file. * doc/gccint/target-macros/adding-support-for-named-address-spaces.rst: New file. * doc/gccint/target-macros/addressing-modes.rst: New file. * doc/gccint/target-macros/adjusting-the-instruction-scheduler.rst: New file. * doc/gccint/target-macros/anchored-addresses.rst: New file. * doc/gccint/target-macros/c++-abi-parameters.rst: New file. * doc/gccint/target-macros/condition-code-status.rst: New file. * doc/gccint/target-macros/controlling-debugging-information-format.rst: New file. * doc/gccint/target-macros/controlling-the-compilation-driver-gcc.rst: New file. * doc/gccint/target-macros/cross-compilation-and-floating-point.rst: New file. * doc/gccint/target-macros/d-abi-parameters.rst: New file. * doc/gccint/target-macros/defining-coprocessor-specifics-for-mips-targets.rst: New file. * doc/gccint/target-macros/defining-data-structures-for-per-function-information.rst: New file. * doc/gccint/target-macros/defining-target-specific-uses-of-attribute.rst: New file. * doc/gccint/target-macros/defining-the-output-assembler-language.rst: New file. * doc/gccint/target-macros/defining-the-output-assembler-language/assembler-commands-for-alignment.rst: New file. * doc/gccint/target-macros/defining-the-output-assembler-language/assembler-commands-for-exception-regions.rst: New file. * doc/gccint/target-macros/defining-the-output-assembler-language/how-initialization-functions-are-handled.rst: New file. * doc/gccint/target-macros/defining-the-output-assembler-language/macros-controlling-initialization-routines.rst: New file. * doc/gccint/target-macros/defining-the-output-assembler-language/output-and-generation-of-labels.rst: New file. * doc/gccint/target-macros/defining-the-output-assembler-language/output-of-assembler-instructions.rst: New file. * doc/gccint/target-macros/defining-the-output-assembler-language/output-of-data.rst: New file. * doc/gccint/target-macros/defining-the-output-assembler-language/output-of-dispatch-tables.rst: New file. * doc/gccint/target-macros/defining-the-output-assembler-language/output-of-uninitialized-variables.rst: New file. * doc/gccint/target-macros/defining-the-output-assembler-language/the-overall-framework-of-an-assembler-file.rst: New file. * doc/gccint/target-macros/describing-relative-costs-of-operations.rst: New file. * doc/gccint/target-macros/dividing-the-output-into-sections-texts-data.rst: New file. * doc/gccint/target-macros/emulating-tls.rst: New file. * doc/gccint/target-macros/implementing-the-varargs-macros.rst: New file. * doc/gccint/target-macros/implicit-calls-to-library-routines.rst: New file. * doc/gccint/target-macros/layout-of-source-language-data-types.rst: New file. * doc/gccint/target-macros/miscellaneous-parameters.rst: New file. * doc/gccint/target-macros/mode-switching-instructions.rst: New file. * doc/gccint/target-macros/parameters-for-precompiled-header-validity-checking.rst: New file. * doc/gccint/target-macros/position-independent-code.rst: New file. * doc/gccint/target-macros/register-classes.rst: New file. * doc/gccint/target-macros/register-usage.rst: New file. * doc/gccint/target-macros/run-time-target-specification.rst: New file. * doc/gccint/target-macros/stack-layout-and-calling-conventions.rst: New file. * doc/gccint/target-macros/stack-layout-and-calling-conventions/basic-stack-layout.rst: New file. * doc/gccint/target-macros/stack-layout-and-calling-conventions/caller-saves-register-allocation.rst: New file. * doc/gccint/target-macros/stack-layout-and-calling-conventions/eliminating-frame-pointer-and-arg-pointer.rst: New file. * doc/gccint/target-macros/stack-layout-and-calling-conventions/exception-handling-support.rst: New file. * doc/gccint/target-macros/stack-layout-and-calling-conventions/function-entry-and-exit.rst: New file. * doc/gccint/target-macros/stack-layout-and-calling-conventions/generating-code-for-profiling.rst: New file. * doc/gccint/target-macros/stack-layout-and-calling-conventions/how-large-values-are-returned.rst: New file. * doc/gccint/target-macros/stack-layout-and-calling-conventions/how-scalar-function-values-are-returned.rst: New file. * doc/gccint/target-macros/stack-layout-and-calling-conventions/miscellaneous-register-hooks.rst: New file. * doc/gccint/target-macros/stack-layout-and-calling-conventions/passing-arguments-in-registers.rst: New file. * doc/gccint/target-macros/stack-layout-and-calling-conventions/passing-function-arguments-on-the-stack.rst: New file. * doc/gccint/target-macros/stack-layout-and-calling-conventions/permitting-tail-calls.rst: New file. * doc/gccint/target-macros/stack-layout-and-calling-conventions/registers-that-address-the-stack-frame.rst: New file. * doc/gccint/target-macros/stack-layout-and-calling-conventions/shrink-wrapping-separate-components.rst: New file. * doc/gccint/target-macros/stack-layout-and-calling-conventions/specifying-how-stack-checking-is-done.rst: New file. * doc/gccint/target-macros/stack-layout-and-calling-conventions/stack-smashing-protection.rst: New file. * doc/gccint/target-macros/storage-layout.rst: New file. * doc/gccint/target-macros/support-for-nested-functions.rst: New file. * doc/gccint/target-macros/the-global-targetm-variable.rst: New file. * doc/gccint/target-makefile-fragments.rst: New file. * doc/gccint/testsuites.rst: New test. * doc/gccint/testsuites/ada-language-testsuites.rst: New test. * doc/gccint/testsuites/c-language-testsuites.rst: New test. * doc/gccint/testsuites/directives-used-within-dejagnu-tests.rst: New test. * doc/gccint/testsuites/directives-used-within-dejagnu-tests/commands-for-use-in-dg-final.rst: New test. * doc/gccint/testsuites/directives-used-within-dejagnu-tests/features-for-dg-add-options.rst: New test. * doc/gccint/testsuites/directives-used-within-dejagnu-tests/keywords-describing-target-attributes.rst: New test. * doc/gccint/testsuites/directives-used-within-dejagnu-tests/selecting-targets-to-which-a-test-applies.rst: New test. * doc/gccint/testsuites/directives-used-within-dejagnu-tests/syntax-and-descriptions-of-test-directives.rst: New test. * doc/gccint/testsuites/directives-used-within-dejagnu-tests/variants-of-dg-require-support.rst: New test. * doc/gccint/testsuites/idioms-used-in-testsuite-code.rst: New test. * doc/gccint/testsuites/support-for-testing-binary-compatibility.rst: New test. * doc/gccint/testsuites/support-for-testing-gcov.rst: New test. * doc/gccint/testsuites/support-for-testing-gimple-passes.rst: New test. * doc/gccint/testsuites/support-for-testing-link-time-optimizations.rst: New test. * doc/gccint/testsuites/support-for-testing-profile-directed-optimizations.rst: New test. * doc/gccint/testsuites/support-for-testing-rtl-passes.rst: New test. * doc/gccint/testsuites/support-for-torture-testing-using-multiple-options.rst: New test. * doc/gccint/the-gcc-low-level-runtime-library.rst: New file. * doc/gccint/the-gcc-low-level-runtime-library/language-independent-routines-for-exception-handling.rst: New file. * doc/gccint/the-gcc-low-level-runtime-library/miscellaneous-runtime-library-routines.rst: New file. * doc/gccint/the-gcc-low-level-runtime-library/routines-for-decimal-floating-point-emulation.rst: New file. * doc/gccint/the-gcc-low-level-runtime-library/routines-for-fixed-point-fractional-emulation.rst: New file. * doc/gccint/the-gcc-low-level-runtime-library/routines-for-floating-point-emulation.rst: New file. * doc/gccint/the-gcc-low-level-runtime-library/routines-for-integer-arithmetic.rst: New file. * doc/gccint/the-language.rst: New file. * doc/gccint/user-experience-guidelines.rst: New file. * doc/install/binaries.rst: New file. * doc/install/building.rst: New file. * doc/install/building/building-a-cross-compiler.rst: New file. * doc/install/building/building-a-native-compiler.rst: New file. * doc/install/building/building-in-parallel.rst: New file. * doc/install/building/building-the-ada-compiler.rst: New file. * doc/install/building/building-the-d-compiler.rst: New file. * doc/install/building/building-with-profile-feedback.rst: New file. * doc/install/conf.py: New file. * doc/install/configuration.rst: New file. * doc/install/copyright.rst: New file. * doc/install/downloading-gcc.rst: New file. * doc/install/final-installation.rst: New file. * doc/install/gnu-free-documentation-license.rst: New file. * doc/install/host-target-specific-installation-notes-for-gcc.rst: New file. * doc/install/how-can-you-run-the-testsuite-on-selected-tests.rst: New test. * doc/install/how-to-interpret-test-results.rst: New file. * doc/install/index.rst: New file. * doc/install/indices-and-tables.rst: New file. * doc/install/installing-gcc.rst: New file. * doc/install/passing-options-and-running-multiple-testsuites.rst: New test. * doc/install/prerequisites.rst: New file. * doc/install/submitting-test-results.rst: New file. * doc/install/testing.rst: New file. gcc/fortran/ChangeLog: * doc/gfc-internals/code-that-interacts-with-the-user.rst: New file. * doc/gfc-internals/command-line-options.rst: New file. * doc/gfc-internals/conf.py: New file. * doc/gfc-internals/copyright.rst: New file. * doc/gfc-internals/error-handling.rst: New file. * doc/gfc-internals/frontend-data-structures.rst: New file. * doc/gfc-internals/generating-the-intermediate-language-for-later-stages.rst: New file. * doc/gfc-internals/generating-the-intermediate-language-for-later-stages/accessing-declarations.rst: New file. * doc/gfc-internals/generating-the-intermediate-language-for-later-stages/basic-data-structures.rst: New file. * doc/gfc-internals/generating-the-intermediate-language-for-later-stages/converting-expressions-to-tree.rst: New file. * doc/gfc-internals/generating-the-intermediate-language-for-later-stages/translating-statements.rst: New file. * doc/gfc-internals/gfccode.rst: New file. * doc/gfc-internals/gfcexpr.rst: New file. * doc/gfc-internals/gnu-free-documentation-license.rst: New file. * doc/gfc-internals/index.rst: New file. * doc/gfc-internals/indices-and-tables.rst: New file. * doc/gfc-internals/internals-of-fortran-2003-oop-features.rst: New file. * doc/gfc-internals/introduction.rst: New file. * doc/gfc-internals/symbol-versioning.rst: New file. * doc/gfc-internals/the-libgfortran-runtime-library.rst: New file. * doc/gfc-internals/type-bound-operators.rst: New file. * doc/gfc-internals/type-bound-procedures.rst: New file. * doc/gfortran/about-gnu-fortran.rst: New file. * doc/gfortran/coarray-programming.rst: New file. * doc/gfortran/compiler-characteristics.rst: New file. * doc/gfortran/compiler-characteristics/asynchronous-i-o.rst: New file. * doc/gfortran/compiler-characteristics/data-consistency-and-durability.rst: New file. * doc/gfortran/compiler-characteristics/evaluation-of-logical-expressions.rst: New file. * doc/gfortran/compiler-characteristics/file-format-of-unformatted-sequential-files.rst: New file. * doc/gfortran/compiler-characteristics/file-operations-on-symbolic-links.rst: New file. * doc/gfortran/compiler-characteristics/files-opened-without-an-explicit-action=-specifier.rst: New file. * doc/gfortran/compiler-characteristics/internal-representation-of-logical-variables.rst: New file. * doc/gfortran/compiler-characteristics/kind-type-parameters.rst: New file. * doc/gfortran/compiler-characteristics/max-and-min-intrinsics-with-real-nan-arguments.rst: New file. * doc/gfortran/compiler-characteristics/thread-safety-of-the-runtime-library.rst: New file. * doc/gfortran/conf.py: New file. * doc/gfortran/contributing.rst: New file. * doc/gfortran/contributors-to-gnu-fortran.rst: New file. * doc/gfortran/copyright.rst: New file. * doc/gfortran/extensions-implemented-in-gnu-fortran.rst: New file. * doc/gfortran/extensions-not-implemented-in-gnu-fortran.rst: New file. * doc/gfortran/extensions.rst: New file. * doc/gfortran/function-abi-documentation.rst: New file. * doc/gfortran/funding.rst: New file. * doc/gfortran/general-public-license-3.rst: New file. * doc/gfortran/gnu-fortran-and-gcc.rst: New file. * doc/gfortran/gnu-fortran-command-options.rst: New file. * doc/gfortran/gnu-fortran-command-options/description.rst: New file. * doc/gfortran/gnu-fortran-command-options/enable-and-customize-preprocessing.rst: New file. * doc/gfortran/gnu-fortran-command-options/environment-variables-affecting-gfortran.rst: New file. * doc/gfortran/gnu-fortran-command-options/influencing-runtime-behavior.rst: New file. * doc/gfortran/gnu-fortran-command-options/influencing-the-linking-step.rst: New file. * doc/gfortran/gnu-fortran-command-options/option-summary.rst: New file. * doc/gfortran/gnu-fortran-command-options/options-controlling-fortran-dialect.rst: New file. * doc/gfortran/gnu-fortran-command-options/options-for-code-generation-conventions.rst: New file. * doc/gfortran/gnu-fortran-command-options/options-for-debugging-your-program-or-gnu-fortran.rst: New file. * doc/gfortran/gnu-fortran-command-options/options-for-directory-search.rst: New file. * doc/gfortran/gnu-fortran-command-options/options-for-interoperability-with-other-languages.rst: New file. * doc/gfortran/gnu-fortran-command-options/options-to-request-or-suppress-errors-and-warnings.rst: New file. * doc/gfortran/gnu-fortran-compiler-directives.rst: New file. * doc/gfortran/gnu-free-documentation-license.rst: New file. * doc/gfortran/index.rst: New file. * doc/gfortran/indices-and-tables.rst: New file. * doc/gfortran/interoperability-with-c.rst: New file. * doc/gfortran/intrinsic-modules.rst: New file. * doc/gfortran/intrinsic-modules/ieee-modules-ieeeexceptions-ieeearithmetic-and-ieeefeatures.rst: New file. * doc/gfortran/intrinsic-modules/isocbinding.rst: New file. * doc/gfortran/intrinsic-modules/isofortranenv.rst: New file. * doc/gfortran/intrinsic-modules/openacc-module-openacc.rst: New file. * doc/gfortran/intrinsic-modules/openmp-modules-omplib-and-omplibkinds.rst: New file. * doc/gfortran/intrinsic-procedures.rst: New file. * doc/gfortran/intrinsic-procedures/abort.rst: New file. * doc/gfortran/intrinsic-procedures/abs.rst: New file. * doc/gfortran/intrinsic-procedures/access.rst: New file. * doc/gfortran/intrinsic-procedures/achar.rst: New file. * doc/gfortran/intrinsic-procedures/acos.rst: New file. * doc/gfortran/intrinsic-procedures/acosd.rst: New file. * doc/gfortran/intrinsic-procedures/acosh.rst: New file. * doc/gfortran/intrinsic-procedures/adjustl.rst: New file. * doc/gfortran/intrinsic-procedures/adjustr.rst: New file. * doc/gfortran/intrinsic-procedures/aimag.rst: New file. * doc/gfortran/intrinsic-procedures/aint.rst: New file. * doc/gfortran/intrinsic-procedures/alarm.rst: New file. * doc/gfortran/intrinsic-procedures/all.rst: New file. * doc/gfortran/intrinsic-procedures/allocated.rst: New file. * doc/gfortran/intrinsic-procedures/and.rst: New file. * doc/gfortran/intrinsic-procedures/anint.rst: New file. * doc/gfortran/intrinsic-procedures/any.rst: New file. * doc/gfortran/intrinsic-procedures/asin.rst: New file. * doc/gfortran/intrinsic-procedures/asind.rst: New file. * doc/gfortran/intrinsic-procedures/asinh.rst: New file. * doc/gfortran/intrinsic-procedures/associated.rst: New file. * doc/gfortran/intrinsic-procedures/atan.rst: New file. * doc/gfortran/intrinsic-procedures/atan2.rst: New file. * doc/gfortran/intrinsic-procedures/atan2d.rst: New file. * doc/gfortran/intrinsic-procedures/atand.rst: New file. * doc/gfortran/intrinsic-procedures/atanh.rst: New file. * doc/gfortran/intrinsic-procedures/atomicadd.rst: New file. * doc/gfortran/intrinsic-procedures/atomicand.rst: New file. * doc/gfortran/intrinsic-procedures/atomiccas.rst: New file. * doc/gfortran/intrinsic-procedures/atomicdefine.rst: New file. * doc/gfortran/intrinsic-procedures/atomicfetchadd.rst: New file. * doc/gfortran/intrinsic-procedures/atomicfetchand.rst: New file. * doc/gfortran/intrinsic-procedures/atomicfetchor.rst: New file. * doc/gfortran/intrinsic-procedures/atomicfetchxor.rst: New file. * doc/gfortran/intrinsic-procedures/atomicor.rst: New file. * doc/gfortran/intrinsic-procedures/atomicref.rst: New file. * doc/gfortran/intrinsic-procedures/atomicxor.rst: New file. * doc/gfortran/intrinsic-procedures/backtrace.rst: New file. * doc/gfortran/intrinsic-procedures/besselj0.rst: New file. * doc/gfortran/intrinsic-procedures/besselj1.rst: New file. * doc/gfortran/intrinsic-procedures/besseljn.rst: New file. * doc/gfortran/intrinsic-procedures/bessely0.rst: New file. * doc/gfortran/intrinsic-procedures/bessely1.rst: New file. * doc/gfortran/intrinsic-procedures/besselyn.rst: New file. * doc/gfortran/intrinsic-procedures/bge.rst: New file. * doc/gfortran/intrinsic-procedures/bgt.rst: New file. * doc/gfortran/intrinsic-procedures/bitsize.rst: New file. * doc/gfortran/intrinsic-procedures/ble.rst: New file. * doc/gfortran/intrinsic-procedures/blt.rst: New file. * doc/gfortran/intrinsic-procedures/btest.rst: New file. * doc/gfortran/intrinsic-procedures/cassociated.rst: New file. * doc/gfortran/intrinsic-procedures/ceiling.rst: New file. * doc/gfortran/intrinsic-procedures/cfpointer.rst: New file. * doc/gfortran/intrinsic-procedures/cfprocpointer.rst: New file. * doc/gfortran/intrinsic-procedures/cfunloc.rst: New file. * doc/gfortran/intrinsic-procedures/char.rst: New file. * doc/gfortran/intrinsic-procedures/chdir.rst: New file. * doc/gfortran/intrinsic-procedures/chmod.rst: New file. * doc/gfortran/intrinsic-procedures/cloc.rst: New file. * doc/gfortran/intrinsic-procedures/cmplx.rst: New file. * doc/gfortran/intrinsic-procedures/cobroadcast.rst: New file. * doc/gfortran/intrinsic-procedures/comax.rst: New file. * doc/gfortran/intrinsic-procedures/comin.rst: New file. * doc/gfortran/intrinsic-procedures/commandargumentcount.rst: New file. * doc/gfortran/intrinsic-procedures/compileroptions.rst: New file. * doc/gfortran/intrinsic-procedures/compilerversion.rst: New file. * doc/gfortran/intrinsic-procedures/complex.rst: New file. * doc/gfortran/intrinsic-procedures/conjg.rst: New file. * doc/gfortran/intrinsic-procedures/coreduce.rst: New file. * doc/gfortran/intrinsic-procedures/cos.rst: New file. * doc/gfortran/intrinsic-procedures/cosd.rst: New file. * doc/gfortran/intrinsic-procedures/cosh.rst: New file. * doc/gfortran/intrinsic-procedures/cosum.rst: New file. * doc/gfortran/intrinsic-procedures/cotan.rst: New file. * doc/gfortran/intrinsic-procedures/cotand.rst: New file. * doc/gfortran/intrinsic-procedures/count.rst: New file. * doc/gfortran/intrinsic-procedures/cputime.rst: New file. * doc/gfortran/intrinsic-procedures/cshift.rst: New file. * doc/gfortran/intrinsic-procedures/csizeof.rst: New file. * doc/gfortran/intrinsic-procedures/ctime.rst: New file. * doc/gfortran/intrinsic-procedures/dateandtime.rst: New file. * doc/gfortran/intrinsic-procedures/dble.rst: New file. * doc/gfortran/intrinsic-procedures/dcmplx.rst: New file. * doc/gfortran/intrinsic-procedures/digits.rst: New file. * doc/gfortran/intrinsic-procedures/dim.rst: New file. * doc/gfortran/intrinsic-procedures/dotproduct.rst: New file. * doc/gfortran/intrinsic-procedures/dprod.rst: New file. * doc/gfortran/intrinsic-procedures/dreal.rst: New file. * doc/gfortran/intrinsic-procedures/dshiftl.rst: New file. * doc/gfortran/intrinsic-procedures/dshiftr.rst: New file. * doc/gfortran/intrinsic-procedures/dtime.rst: New file. * doc/gfortran/intrinsic-procedures/eoshift.rst: New file. * doc/gfortran/intrinsic-procedures/epsilon.rst: New file. * doc/gfortran/intrinsic-procedures/erf.rst: New file. * doc/gfortran/intrinsic-procedures/erfc.rst: New file. * doc/gfortran/intrinsic-procedures/erfcscaled.rst: New file. * doc/gfortran/intrinsic-procedures/etime.rst: New file. * doc/gfortran/intrinsic-procedures/eventquery.rst: New file. * doc/gfortran/intrinsic-procedures/executecommandline.rst: New file. * doc/gfortran/intrinsic-procedures/exit.rst: New file. * doc/gfortran/intrinsic-procedures/exp.rst: New file. * doc/gfortran/intrinsic-procedures/exponent.rst: New file. * doc/gfortran/intrinsic-procedures/extendstypeof.rst: New file. * doc/gfortran/intrinsic-procedures/fdate.rst: New file. * doc/gfortran/intrinsic-procedures/fget.rst: New file. * doc/gfortran/intrinsic-procedures/fgetc.rst: New file. * doc/gfortran/intrinsic-procedures/findloc.rst: New file. * doc/gfortran/intrinsic-procedures/floor.rst: New file. * doc/gfortran/intrinsic-procedures/flush.rst: New file. * doc/gfortran/intrinsic-procedures/fnum.rst: New file. * doc/gfortran/intrinsic-procedures/fput.rst: New file. * doc/gfortran/intrinsic-procedures/fputc.rst: New file. * doc/gfortran/intrinsic-procedures/fraction.rst: New file. * doc/gfortran/intrinsic-procedures/free.rst: New file. * doc/gfortran/intrinsic-procedures/fseek.rst: New file. * doc/gfortran/intrinsic-procedures/fstat.rst: New file. * doc/gfortran/intrinsic-procedures/ftell.rst: New file. * doc/gfortran/intrinsic-procedures/gamma.rst: New file. * doc/gfortran/intrinsic-procedures/gerror.rst: New file. * doc/gfortran/intrinsic-procedures/getarg.rst: New file. * doc/gfortran/intrinsic-procedures/getcommand.rst: New file. * doc/gfortran/intrinsic-procedures/getcommandargument.rst: New file. * doc/gfortran/intrinsic-procedures/getcwd.rst: New file. * doc/gfortran/intrinsic-procedures/getenv.rst: New file. * doc/gfortran/intrinsic-procedures/getenvironmentvariable.rst: New file. * doc/gfortran/intrinsic-procedures/getgid.rst: New file. * doc/gfortran/intrinsic-procedures/getlog.rst: New file. * doc/gfortran/intrinsic-procedures/getpid.rst: New file. * doc/gfortran/intrinsic-procedures/getuid.rst: New file. * doc/gfortran/intrinsic-procedures/gmtime.rst: New file. * doc/gfortran/intrinsic-procedures/hostnm.rst: New file. * doc/gfortran/intrinsic-procedures/huge.rst: New file. * doc/gfortran/intrinsic-procedures/hypot.rst: New file. * doc/gfortran/intrinsic-procedures/iachar.rst: New file. * doc/gfortran/intrinsic-procedures/iall.rst: New file. * doc/gfortran/intrinsic-procedures/iand.rst: New file. * doc/gfortran/intrinsic-procedures/iany.rst: New file. * doc/gfortran/intrinsic-procedures/iargc.rst: New file. * doc/gfortran/intrinsic-procedures/ibclr.rst: New file. * doc/gfortran/intrinsic-procedures/ibits.rst: New file. * doc/gfortran/intrinsic-procedures/ibset.rst: New file. * doc/gfortran/intrinsic-procedures/ichar.rst: New file. * doc/gfortran/intrinsic-procedures/idate.rst: New file. * doc/gfortran/intrinsic-procedures/ieor.rst: New file. * doc/gfortran/intrinsic-procedures/ierrno.rst: New file. * doc/gfortran/intrinsic-procedures/imageindex.rst: New file. * doc/gfortran/intrinsic-procedures/index.rst: New file. * doc/gfortran/intrinsic-procedures/int.rst: New file. * doc/gfortran/intrinsic-procedures/int2.rst: New file. * doc/gfortran/intrinsic-procedures/int8.rst: New file. * doc/gfortran/intrinsic-procedures/introduction-to-intrinsic-procedures.rst: New file. * doc/gfortran/intrinsic-procedures/ior.rst: New file. * doc/gfortran/intrinsic-procedures/iparity.rst: New file. * doc/gfortran/intrinsic-procedures/irand.rst: New file. * doc/gfortran/intrinsic-procedures/isatty.rst: New file. * doc/gfortran/intrinsic-procedures/iscontiguous.rst: New file. * doc/gfortran/intrinsic-procedures/ishft.rst: New file. * doc/gfortran/intrinsic-procedures/ishftc.rst: New file. * doc/gfortran/intrinsic-procedures/isiostatend.rst: New file. * doc/gfortran/intrinsic-procedures/isiostateor.rst: New file. * doc/gfortran/intrinsic-procedures/isnan.rst: New file. * doc/gfortran/intrinsic-procedures/itime.rst: New file. * doc/gfortran/intrinsic-procedures/kill.rst: New file. * doc/gfortran/intrinsic-procedures/kind.rst: New file. * doc/gfortran/intrinsic-procedures/lbound.rst: New file. * doc/gfortran/intrinsic-procedures/lcobound.rst: New file. * doc/gfortran/intrinsic-procedures/leadz.rst: New file. * doc/gfortran/intrinsic-procedures/len.rst: New file. * doc/gfortran/intrinsic-procedures/lentrim.rst: New file. * doc/gfortran/intrinsic-procedures/lge.rst: New file. * doc/gfortran/intrinsic-procedures/lgt.rst: New file. * doc/gfortran/intrinsic-procedures/link.rst: New file. * doc/gfortran/intrinsic-procedures/lle.rst: New file. * doc/gfortran/intrinsic-procedures/llt.rst: New file. * doc/gfortran/intrinsic-procedures/lnblnk.rst: New file. * doc/gfortran/intrinsic-procedures/loc.rst: New file. * doc/gfortran/intrinsic-procedures/log.rst: New file. * doc/gfortran/intrinsic-procedures/log10.rst: New file. * doc/gfortran/intrinsic-procedures/loggamma.rst: New file. * doc/gfortran/intrinsic-procedures/logical.rst: New file. * doc/gfortran/intrinsic-procedures/lshift.rst: New file. * doc/gfortran/intrinsic-procedures/lstat.rst: New file. * doc/gfortran/intrinsic-procedures/ltime.rst: New file. * doc/gfortran/intrinsic-procedures/malloc.rst: New file. * doc/gfortran/intrinsic-procedures/maskl.rst: New file. * doc/gfortran/intrinsic-procedures/maskr.rst: New file. * doc/gfortran/intrinsic-procedures/matmul.rst: New file. * doc/gfortran/intrinsic-procedures/max.rst: New file. * doc/gfortran/intrinsic-procedures/maxexponent.rst: New file. * doc/gfortran/intrinsic-procedures/maxloc.rst: New file. * doc/gfortran/intrinsic-procedures/maxval.rst: New file. * doc/gfortran/intrinsic-procedures/mclock.rst: New file. * doc/gfortran/intrinsic-procedures/mclock8.rst: New file. * doc/gfortran/intrinsic-procedures/merge.rst: New file. * doc/gfortran/intrinsic-procedures/mergebits.rst: New file. * doc/gfortran/intrinsic-procedures/min.rst: New file. * doc/gfortran/intrinsic-procedures/minexponent.rst: New file. * doc/gfortran/intrinsic-procedures/minloc.rst: New file. * doc/gfortran/intrinsic-procedures/minval.rst: New file. * doc/gfortran/intrinsic-procedures/mod.rst: New file. * doc/gfortran/intrinsic-procedures/modulo.rst: New file. * doc/gfortran/intrinsic-procedures/movealloc.rst: New file. * doc/gfortran/intrinsic-procedures/mvbits.rst: New file. * doc/gfortran/intrinsic-procedures/nearest.rst: New file. * doc/gfortran/intrinsic-procedures/newline.rst: New file. * doc/gfortran/intrinsic-procedures/nint.rst: New file. * doc/gfortran/intrinsic-procedures/norm2.rst: New file. * doc/gfortran/intrinsic-procedures/not.rst: New file. * doc/gfortran/intrinsic-procedures/null.rst: New file. * doc/gfortran/intrinsic-procedures/numimages.rst: New file. * doc/gfortran/intrinsic-procedures/or.rst: New file. * doc/gfortran/intrinsic-procedures/pack.rst: New file. * doc/gfortran/intrinsic-procedures/parity.rst: New file. * doc/gfortran/intrinsic-procedures/perror.rst: New file. * doc/gfortran/intrinsic-procedures/popcnt.rst: New file. * doc/gfortran/intrinsic-procedures/poppar.rst: New file. * doc/gfortran/intrinsic-procedures/precision.rst: New file. * doc/gfortran/intrinsic-procedures/present.rst: New file. * doc/gfortran/intrinsic-procedures/product.rst: New file. * doc/gfortran/intrinsic-procedures/radix.rst: New file. * doc/gfortran/intrinsic-procedures/ran.rst: New file. * doc/gfortran/intrinsic-procedures/rand.rst: New file. * doc/gfortran/intrinsic-procedures/randominit.rst: New file. * doc/gfortran/intrinsic-procedures/randomnumber.rst: New file. * doc/gfortran/intrinsic-procedures/randomseed.rst: New file. * doc/gfortran/intrinsic-procedures/range.rst: New file. * doc/gfortran/intrinsic-procedures/rank.rst: New file. * doc/gfortran/intrinsic-procedures/real.rst: New file. * doc/gfortran/intrinsic-procedures/rename.rst: New file. * doc/gfortran/intrinsic-procedures/repeat.rst: New file. * doc/gfortran/intrinsic-procedures/reshape.rst: New file. * doc/gfortran/intrinsic-procedures/rrspacing.rst: New file. * doc/gfortran/intrinsic-procedures/rshift.rst: New file. * doc/gfortran/intrinsic-procedures/sametypeas.rst: New file. * doc/gfortran/intrinsic-procedures/scale.rst: New file. * doc/gfortran/intrinsic-procedures/scan.rst: New file. * doc/gfortran/intrinsic-procedures/secnds.rst: New file. * doc/gfortran/intrinsic-procedures/second.rst: New file. * doc/gfortran/intrinsic-procedures/selectedcharkind.rst: New file. * doc/gfortran/intrinsic-procedures/selectedintkind.rst: New file. * doc/gfortran/intrinsic-procedures/selectedrealkind.rst: New file. * doc/gfortran/intrinsic-procedures/setexponent.rst: New file. * doc/gfortran/intrinsic-procedures/shape.rst: New file. * doc/gfortran/intrinsic-procedures/shifta.rst: New file. * doc/gfortran/intrinsic-procedures/shiftl.rst: New file. * doc/gfortran/intrinsic-procedures/shiftr.rst: New file. * doc/gfortran/intrinsic-procedures/sign.rst: New file. * doc/gfortran/intrinsic-procedures/signal.rst: New file. * doc/gfortran/intrinsic-procedures/sin.rst: New file. * doc/gfortran/intrinsic-procedures/sind.rst: New file. * doc/gfortran/intrinsic-procedures/sinh.rst: New file. * doc/gfortran/intrinsic-procedures/size.rst: New file. * doc/gfortran/intrinsic-procedures/sizeof.rst: New file. * doc/gfortran/intrinsic-procedures/sleep.rst: New file. * doc/gfortran/intrinsic-procedures/spacing.rst: New file. * doc/gfortran/intrinsic-procedures/spread.rst: New file. * doc/gfortran/intrinsic-procedures/sqrt.rst: New file. * doc/gfortran/intrinsic-procedures/srand.rst: New file. * doc/gfortran/intrinsic-procedures/stat.rst: New file. * doc/gfortran/intrinsic-procedures/storagesize.rst: New file. * doc/gfortran/intrinsic-procedures/sum.rst: New file. * doc/gfortran/intrinsic-procedures/symlnk.rst: New file. * doc/gfortran/intrinsic-procedures/system.rst: New file. * doc/gfortran/intrinsic-procedures/systemclock.rst: New file. * doc/gfortran/intrinsic-procedures/tan.rst: New file. * doc/gfortran/intrinsic-procedures/tand.rst: New file. * doc/gfortran/intrinsic-procedures/tanh.rst: New file. * doc/gfortran/intrinsic-procedures/thisimage.rst: New file. * doc/gfortran/intrinsic-procedures/time.rst: New file. * doc/gfortran/intrinsic-procedures/time8.rst: New file. * doc/gfortran/intrinsic-procedures/tiny.rst: New file. * doc/gfortran/intrinsic-procedures/trailz.rst: New file. * doc/gfortran/intrinsic-procedures/transfer.rst: New file. * doc/gfortran/intrinsic-procedures/transpose.rst: New file. * doc/gfortran/intrinsic-procedures/trim.rst: New file. * doc/gfortran/intrinsic-procedures/ttynam.rst: New file. * doc/gfortran/intrinsic-procedures/ubound.rst: New file. * doc/gfortran/intrinsic-procedures/ucobound.rst: New file. * doc/gfortran/intrinsic-procedures/umask.rst: New file. * doc/gfortran/intrinsic-procedures/unlink.rst: New file. * doc/gfortran/intrinsic-procedures/unpack.rst: New file. * doc/gfortran/intrinsic-procedures/verify.rst: New file. * doc/gfortran/intrinsic-procedures/xor.rst: New file. * doc/gfortran/introduction.rst: New file. * doc/gfortran/mixed-language-programming.rst: New file. * doc/gfortran/naming-and-argument-passing-conventions.rst: New file. * doc/gfortran/non-fortran-main-program.rst: New file. * doc/gfortran/projects.rst: New file. * doc/gfortran/runtime.rst: New file. * doc/gfortran/runtime/gfortranconvertunit.rst: New file. * doc/gfortran/runtime/gfortranerrorbacktrace.rst: New file. * doc/gfortran/runtime/gfortranformattedbuffersize.rst: New file. * doc/gfortran/runtime/gfortranlistseparator.rst: New file. * doc/gfortran/runtime/gfortranoptionalplus.rst: New file. * doc/gfortran/runtime/gfortranshowlocus.rst: New file. * doc/gfortran/runtime/gfortranstderrunit.rst: New file. * doc/gfortran/runtime/gfortranstdinunit.rst: New file. * doc/gfortran/runtime/gfortranstdoutunit.rst: New file. * doc/gfortran/runtime/gfortranunbufferedall.rst: New file. * doc/gfortran/runtime/gfortranunbufferedpreconnected.rst: New file. * doc/gfortran/runtime/gfortranunformattedbuffersize.rst: New file. * doc/gfortran/runtime/tmpdir.rst: New file. * doc/gfortran/standards.rst: New file. * doc/gfortran/type-and-enum-abi-documentation.rst: New file. gcc/go/ChangeLog: * doc/c-interoperability.rst: New file. * doc/c-type-interoperability.rst: New file. * doc/compiler-directives.rst: New file. * doc/conf.py: New file. * doc/copyright.rst: New file. * doc/function-names.rst: New file. * doc/general-public-license-3.rst: New file. * doc/gnu-free-documentation-license.rst: New file. * doc/import-and-export.rst: New file. * doc/index.rst: New file. * doc/indices-and-tables.rst: New file. * doc/introduction.rst: New file. * doc/invoking-gccgo.rst: New file. libgomp/ChangeLog: * doc/amd-radeon-gcn.rst: New file. * doc/conf.py: New file. * doc/copyright.rst: New file. * doc/cuda-streams-usage.rst: New file. * doc/enabling-openacc.rst: New file. * doc/enabling-openmp.rst: New file. * doc/first-invocation-nvidia-cublas-library-api.rst: New file. * doc/first-invocation-openacc-library-api.rst: New file. * doc/funding.rst: New file. * doc/general-public-license-3.rst: New file. * doc/gnu-free-documentation-license.rst: New file. * doc/implementation-status-and-implementation-defined-behavior.rst: New file. * doc/index.rst: New file. * doc/indices-and-tables.rst: New file. * doc/introduction.rst: New file. * doc/memory-allocation-with-libmemkind.rst: New file. * doc/nvptx.rst: New file. * doc/offload-target-specifics.rst: New file. * doc/openacc-environment-variables.rst: New file. * doc/openacc-environment-variables/accdevicenum.rst: New file. * doc/openacc-environment-variables/accdevicetype.rst: New file. * doc/openacc-environment-variables/accproflib.rst: New file. * doc/openacc-environment-variables/gccaccnotify.rst: New file. * doc/openacc-introduction.rst: New file. * doc/openacc-library-and-environment-variables.rst: New file. * doc/openacc-library-interoperability.rst: New file. * doc/openacc-profiling-interface.rst: New file. * doc/openacc-runtime-library-routines.rst: New file. * doc/openacc-runtime-library-routines/accasynctest.rst: New file. * doc/openacc-runtime-library-routines/accasynctestall.rst: New file. * doc/openacc-runtime-library-routines/accattach.rst: New file. * doc/openacc-runtime-library-routines/acccopyin.rst: New file. * doc/openacc-runtime-library-routines/acccopyout.rst: New file. * doc/openacc-runtime-library-routines/acccreate.rst: New file. * doc/openacc-runtime-library-routines/accdelete.rst: New file. * doc/openacc-runtime-library-routines/accdetach.rst: New file. * doc/openacc-runtime-library-routines/accdeviceptr.rst: New file. * doc/openacc-runtime-library-routines/accfree.rst: New file. * doc/openacc-runtime-library-routines/accgetcudastream.rst: New file. * doc/openacc-runtime-library-routines/accgetcurrentcudacontext.rst: New file. * doc/openacc-runtime-library-routines/accgetcurrentcudadevice.rst: New file. * doc/openacc-runtime-library-routines/accgetdevicenum.rst: New file. * doc/openacc-runtime-library-routines/accgetdevicetype.rst: New file. * doc/openacc-runtime-library-routines/accgetnumdevices.rst: New file. * doc/openacc-runtime-library-routines/accgetproperty.rst: New file. * doc/openacc-runtime-library-routines/acchostptr.rst: New file. * doc/openacc-runtime-library-routines/accinit.rst: New file. * doc/openacc-runtime-library-routines/accispresent.rst: New file. * doc/openacc-runtime-library-routines/accmalloc.rst: New file. * doc/openacc-runtime-library-routines/accmapdata.rst: New file. * doc/openacc-runtime-library-routines/accmemcpyfromdevice.rst: New file. * doc/openacc-runtime-library-routines/accmemcpytodevice.rst: New file. * doc/openacc-runtime-library-routines/accondevice.rst: New file. * doc/openacc-runtime-library-routines/accpresentorcopyin.rst: New file. * doc/openacc-runtime-library-routines/accpresentorcreate.rst: New file. * doc/openacc-runtime-library-routines/accproflookup.rst: New file. * doc/openacc-runtime-library-routines/accprofregister.rst: New file. * doc/openacc-runtime-library-routines/accprofunregister.rst: New file. * doc/openacc-runtime-library-routines/accregisterlibrary.rst: New file. * doc/openacc-runtime-library-routines/accsetcudastream.rst: New file. * doc/openacc-runtime-library-routines/accsetdevicenum.rst: New file. * doc/openacc-runtime-library-routines/accsetdevicetype.rst: New file. * doc/openacc-runtime-library-routines/accshutdown.rst: New file. * doc/openacc-runtime-library-routines/accunmapdata.rst: New file. * doc/openacc-runtime-library-routines/accupdatedevice.rst: New file. * doc/openacc-runtime-library-routines/accupdateself.rst: New file. * doc/openacc-runtime-library-routines/accwait.rst: New file. * doc/openacc-runtime-library-routines/accwaitall.rst: New file. * doc/openacc-runtime-library-routines/accwaitallasync.rst: New file. * doc/openacc-runtime-library-routines/accwaitasync.rst: New file. * doc/openmp-context-selectors.rst: New file. * doc/openmp-environment-variables.rst: New file. * doc/openmp-environment-variables/gompcpuaffinity.rst: New file. * doc/openmp-environment-variables/gompdebug.rst: New file. * doc/openmp-environment-variables/gomprtemsthreadpools.rst: New file. * doc/openmp-environment-variables/gompspincount.rst: New file. * doc/openmp-environment-variables/gompstacksize.rst: New file. * doc/openmp-environment-variables/ompcancellation.rst: New file. * doc/openmp-environment-variables/ompdefaultdevice.rst: New file. * doc/openmp-environment-variables/ompdisplayenv.rst: New file. * doc/openmp-environment-variables/ompdynamic.rst: New file. * doc/openmp-environment-variables/ompmaxactivelevels.rst: New file. * doc/openmp-environment-variables/ompmaxtaskpriority.rst: New file. * doc/openmp-environment-variables/ompnested.rst: New file. * doc/openmp-environment-variables/ompnumteams.rst: New file. * doc/openmp-environment-variables/ompnumthreads.rst: New file. * doc/openmp-environment-variables/ompplaces.rst: New file. * doc/openmp-environment-variables/ompprocbind.rst: New file. * doc/openmp-environment-variables/ompschedule.rst: New file. * doc/openmp-environment-variables/ompstacksize.rst: New file. * doc/openmp-environment-variables/omptargetoffload.rst: New file. * doc/openmp-environment-variables/ompteamsthreadlimit.rst: New file. * doc/openmp-environment-variables/ompthreadlimit.rst: New file. * doc/openmp-environment-variables/ompwaitpolicy.rst: New file. * doc/openmp-implementation-specifics.rst: New file. * doc/openmp-implementation-status.rst: New file. * doc/openmp-implementation-status/openmp-45.rst: New file. * doc/openmp-implementation-status/openmp-50.rst: New file. * doc/openmp-implementation-status/openmp-51.rst: New file. * doc/openmp-implementation-status/openmp-52.rst: New file. * doc/openmp-runtime-library-routines.rst: New file. * doc/openmp-runtime-library-routines/ompdestroylock.rst: New file. * doc/openmp-runtime-library-routines/ompdestroynestlock.rst: New file. * doc/openmp-runtime-library-routines/ompfulfillevent.rst: New file. * doc/openmp-runtime-library-routines/ompgetactivelevel.rst: New file. * doc/openmp-runtime-library-routines/ompgetancestorthreadnum.rst: New file. * doc/openmp-runtime-library-routines/ompgetcancellation.rst: New file. * doc/openmp-runtime-library-routines/ompgetdefaultdevice.rst: New file. * doc/openmp-runtime-library-routines/ompgetdevicenum.rst: New file. * doc/openmp-runtime-library-routines/ompgetdynamic.rst: New file. * doc/openmp-runtime-library-routines/ompgetinitialdevice.rst: New file. * doc/openmp-runtime-library-routines/ompgetlevel.rst: New file. * doc/openmp-runtime-library-routines/ompgetmaxactivelevels.rst: New file. * doc/openmp-runtime-library-routines/ompgetmaxtaskpriority.rst: New file. * doc/openmp-runtime-library-routines/ompgetmaxteams.rst: New file. * doc/openmp-runtime-library-routines/ompgetmaxthreads.rst: New file. * doc/openmp-runtime-library-routines/ompgetnested.rst: New file. * doc/openmp-runtime-library-routines/ompgetnumdevices.rst: New file. * doc/openmp-runtime-library-routines/ompgetnumprocs.rst: New file. * doc/openmp-runtime-library-routines/ompgetnumteams.rst: New file. * doc/openmp-runtime-library-routines/ompgetnumthreads.rst: New file. * doc/openmp-runtime-library-routines/ompgetprocbind.rst: New file. * doc/openmp-runtime-library-routines/ompgetschedule.rst: New file. * doc/openmp-runtime-library-routines/ompgetsupportedactivelevels.rst: New file. * doc/openmp-runtime-library-routines/ompgetteamnum.rst: New file. * doc/openmp-runtime-library-routines/ompgetteamsize.rst: New file. * doc/openmp-runtime-library-routines/ompgetteamsthreadlimit.rst: New file. * doc/openmp-runtime-library-routines/ompgetthreadlimit.rst: New file. * doc/openmp-runtime-library-routines/ompgetthreadnum.rst: New file. * doc/openmp-runtime-library-routines/ompgetwtick.rst: New file. * doc/openmp-runtime-library-routines/ompgetwtime.rst: New file. * doc/openmp-runtime-library-routines/ompinfinal.rst: New file. * doc/openmp-runtime-library-routines/ompinitlock.rst: New file. * doc/openmp-runtime-library-routines/ompinitnestlock.rst: New file. * doc/openmp-runtime-library-routines/ompinparallel.rst: New file. * doc/openmp-runtime-library-routines/ompisinitialdevice.rst: New file. * doc/openmp-runtime-library-routines/ompsetdefaultdevice.rst: New file. * doc/openmp-runtime-library-routines/ompsetdynamic.rst: New file. * doc/openmp-runtime-library-routines/ompsetlock.rst: New file. * doc/openmp-runtime-library-routines/ompsetmaxactivelevels.rst: New file. * doc/openmp-runtime-library-routines/ompsetnested.rst: New file. * doc/openmp-runtime-library-routines/ompsetnestlock.rst: New file. * doc/openmp-runtime-library-routines/ompsetnumteams.rst: New file. * doc/openmp-runtime-library-routines/ompsetnumthreads.rst: New file. * doc/openmp-runtime-library-routines/ompsetschedule.rst: New file. * doc/openmp-runtime-library-routines/ompsetteamsthreadlimit.rst: New file. * doc/openmp-runtime-library-routines/omptestlock.rst: New file. * doc/openmp-runtime-library-routines/omptestnestlock.rst: New file. * doc/openmp-runtime-library-routines/ompunsetlock.rst: New file. * doc/openmp-runtime-library-routines/ompunsetnestlock.rst: New file. * doc/reporting-bugs.rst: New file. * doc/the-libgomp-abi.rst: New file. * doc/the-libgomp-abi/implementing-atomic-construct.rst: New file. * doc/the-libgomp-abi/implementing-barrier-construct.rst: New file. * doc/the-libgomp-abi/implementing-critical-construct.rst: New file. * doc/the-libgomp-abi/implementing-firstprivate-lastprivate-copyin-and-copyprivate-clauses.rst: New file. * doc/the-libgomp-abi/implementing-flush-construct.rst: New file. * doc/the-libgomp-abi/implementing-for-construct.rst: New file. * doc/the-libgomp-abi/implementing-master-construct.rst: New file. * doc/the-libgomp-abi/implementing-openaccs-parallel-construct.rst: New file. * doc/the-libgomp-abi/implementing-ordered-construct.rst: New file. * doc/the-libgomp-abi/implementing-parallel-construct.rst: New file. * doc/the-libgomp-abi/implementing-private-clause.rst: New file. * doc/the-libgomp-abi/implementing-reduction-clause.rst: New file. * doc/the-libgomp-abi/implementing-sections-construct.rst: New file. * doc/the-libgomp-abi/implementing-single-construct.rst: New file. * doc/the-libgomp-abi/implementing-threadprivate-construct.rst: New file. libiberty/ChangeLog: * doc/bsd.rst: New file. * doc/conf.py: New file. * doc/copyright.rst: New file. * doc/extensions.rst: New file. * doc/function-variable-and-macro-listing.rst: New file. * doc/index.rst: New file. * doc/indices-and-tables.rst: New file. * doc/introduction.rst: New file. * doc/lesser-general-public-license-2.1.rst: New file. * doc/overview.rst: New file. * doc/replacement-functions.rst: New file. * doc/supplemental-functions.rst: New file. * doc/using.rst: New file. libitm/ChangeLog: * doc/c-c++-language-constructs-for-tm.rst: New file. * doc/conf.py: New file. * doc/copyright.rst: New file. * doc/enabling-libitm.rst: New file. * doc/gnu-free-documentation-license.rst: New file. * doc/index.rst: New file. * doc/indices-and-tables.rst: New file. * doc/internals.rst: New file. * doc/locking-conventions.rst: New file. * doc/nesting-flat-vs-closed.rst: New file. * doc/the-libitm-abi.rst: New file. * doc/the-libitm-abi/function-list.rst: New file. * doc/the-libitm-abi/future-enhancements-to-the-abi.rst: New file. * doc/the-libitm-abi/library-design-principles.rst: New file. * doc/the-libitm-abi/memory-model.rst: New file. * doc/the-libitm-abi/non-objectives.rst: New file. * doc/the-libitm-abi/objectives.rst: New file. * doc/the-libitm-abi/sample-code.rst: New file. * doc/the-libitm-abi/types-and-macros-list.rst: New file. * doc/tm-methods-and-method-groups.rst: New file. libquadmath/ChangeLog: * doc/conf.py: New file. * doc/copyright.rst: New file. * doc/gnu-free-documentation-license.rst: New file. * doc/i-o-library-routines.rst: New file. * doc/index.rst: New file. * doc/indices-and-tables.rst: New file. * doc/introduction.rst: New file. * doc/math-library-routines.rst: New file. * doc/quadmathsnprintf.rst: New file. * doc/reporting-bugs.rst: New file. * doc/strtoflt128.rst: New file. * doc/typedef-and-constants.rst: New file. Diff: --- doc/Makefile | 97 + doc/_static/custom.css | 11 + doc/baseconf.py | 230 + doc/bsd.rst | 39 + doc/contrib.rst | 1273 +++++ doc/contribute.rst | 21 + doc/cppdiropts.rst | 217 + doc/cppenv.rst | 97 + doc/cppopts.rst | 556 +++ doc/cppwarnopts.rst | 4 + doc/favicon.ico | Bin 0 -> 766 bytes doc/funding.rst | 47 + doc/gcc_sphinx.py | 44 + doc/gnu.rst | 19 + doc/gnu_free_documentation_license.rst | 476 ++ doc/gpl-3.0.rst | 707 +++ doc/indices-and-tables.rst | 13 + doc/lgpl-2.1.rst | 514 +++ doc/logo.pdf | Bin 0 -> 8978 bytes doc/logo.svg | 108 + doc/md.rst | 3142 +++++++++++++ doc/requirements.txt | 3 + gcc/d/doc/conf.py | 30 + gcc/d/doc/copyright.rst | 13 + gcc/d/doc/general-public-license-3.rst | 6 + gcc/d/doc/gnu-free-documentation-license.rst | 6 + gcc/d/doc/index.rst | 22 + gcc/d/doc/indices-and-tables.rst | 1 + gcc/d/doc/invoking-gdc.rst | 48 + gcc/d/doc/invoking-gdc/code-generation.rst | 170 + gcc/d/doc/invoking-gdc/developer-options.rst | 31 + gcc/d/doc/invoking-gdc/input-and-output-files.rst | 45 + .../invoking-gdc/options-for-directory-search.rst | 92 + gcc/d/doc/invoking-gdc/options-for-linking.rst | 59 + gcc/d/doc/invoking-gdc/runtime-options.rst | 314 ++ gcc/d/doc/invoking-gdc/warnings.rst | 148 + gcc/doc/cpp/character-sets.rst | 56 + gcc/doc/cpp/conditional-syntax.rst | 411 ++ gcc/doc/cpp/conditional-uses.rst | 32 + gcc/doc/cpp/conditionals.rst | 44 + gcc/doc/cpp/conf.py | 30 + gcc/doc/cpp/copyright.rst | 24 + gcc/doc/cpp/deleted-code.rst | 34 + gcc/doc/cpp/diagnostics.rst | 51 + gcc/doc/cpp/environment-variables.rst | 23 + gcc/doc/cpp/gnu-free-documentation-license.rst | 6 + gcc/doc/cpp/header-files.rst | 56 + .../alternatives-to-wrapper-ifndef.rst | 40 + gcc/doc/cpp/header-files/computed-includes.rst | 86 + gcc/doc/cpp/header-files/include-operation.rst | 67 + gcc/doc/cpp/header-files/include-syntax.rst | 42 + gcc/doc/cpp/header-files/once-only-headers.rst | 52 + gcc/doc/cpp/header-files/search-path.rst | 53 + gcc/doc/cpp/header-files/system-headers.rst | 41 + gcc/doc/cpp/header-files/wrapper-headers.rst | 58 + gcc/doc/cpp/implementation-defined-behavior.rst | 97 + gcc/doc/cpp/implementation-details.rst | 23 + gcc/doc/cpp/implementation-limits.rst | 68 + gcc/doc/cpp/index.rst | 35 + gcc/doc/cpp/indices-and-tables.rst | 1 + gcc/doc/cpp/initial-processing.rst | 164 + gcc/doc/cpp/invocation.rst | 81 + gcc/doc/cpp/line-control.rst | 55 + gcc/doc/cpp/macros.rst | 37 + gcc/doc/cpp/macros/concatenation.rst | 85 + .../macros/directives-within-macro-arguments.rst | 39 + gcc/doc/cpp/macros/function-like-macros.rst | 55 + gcc/doc/cpp/macros/macro-arguments.rst | 112 + gcc/doc/cpp/macros/macro-pitfalls.rst | 449 ++ gcc/doc/cpp/macros/object-like-macros.rst | 126 + gcc/doc/cpp/macros/predefined-macros.rst | 874 ++++ gcc/doc/cpp/macros/stringizing.rst | 86 + .../macros/undefining-and-redefining-macros.rst | 67 + gcc/doc/cpp/macros/variadic-macros.rst | 141 + gcc/doc/cpp/obsolete-features.rst | 98 + gcc/doc/cpp/other-directives.rst | 30 + gcc/doc/cpp/overview.rst | 67 + gcc/doc/cpp/pragmas.rst | 121 + gcc/doc/cpp/preprocessor-output.rst | 86 + gcc/doc/cpp/the-preprocessing-language.rst | 69 + gcc/doc/cpp/tokenization.rst | 168 + gcc/doc/cpp/traditional-lexical-analysis.rst | 74 + gcc/doc/cpp/traditional-macros.rst | 99 + gcc/doc/cpp/traditional-miscellany.rst | 30 + gcc/doc/cpp/traditional-mode.rst | 35 + gcc/doc/cpp/traditional-warnings.rst | 49 + gcc/doc/cppinternals/conf.py | 24 + gcc/doc/cppinternals/copyright.rst | 19 + gcc/doc/cppinternals/cppinternals.rst | 284 ++ gcc/doc/cppinternals/cpplib.rst | 29 + gcc/doc/cppinternals/files.rst | 70 + gcc/doc/cppinternals/index.rst | 21 + gcc/doc/cppinternals/indices-and-tables.rst | 1 + .../internal-representation-of-macros.rst | 27 + .../cppinternals/just-which-line-number-anyway.rst | 62 + gcc/doc/cppinternals/lexing-a-line.rst | 91 + gcc/doc/cppinternals/lexing-a-token.rst | 177 + ...-a-function-like-macros-opening-parenthesis.rst | 24 + gcc/doc/cppinternals/macro-expansion-overview.rst | 51 + ...king-tokens-ineligible-for-future-expansion.rst | 24 + .../cppinternals/multiple-include-optimization.rst | 117 + gcc/doc/cppinternals/overview.rst | 24 + .../representation-of-line-numbers.rst | 32 + ...g-the-replacement-list-for-macros-to-expand.rst | 57 + gcc/doc/gcc/binary-compatibility.rst | 151 + .../gcc/c++-implementation-defined-behavior.rst | 33 + gcc/doc/gcc/c-implementation-defined-behavior.rst | 46 + .../architecture.rst | 47 + .../arrays-and-pointers.rst | 46 + .../characters.rst | 93 + .../declarators.rst | 14 + .../environment.rst | 18 + .../floating-point.rst | 88 + .../c-implementation-defined-behavior/hints.rst | 35 + .../identifiers.rst | 28 + .../c-implementation-defined-behavior/integers.rst | 66 + .../library-functions.rst | 19 + .../locale-specific-behavior.rst | 12 + .../preprocessing-directives.rst | 54 + .../qualifiers.rst | 53 + .../statements.rst | 14 + ...ructures-unions-enumerations-and-bit-fields.rst | 78 + .../translation.rst | 20 + gcc/doc/gcc/conditionally-supported-behavior.rst | 20 + gcc/doc/gcc/conf.py | 37 + gcc/doc/gcc/contributing-to-gcc-development.rst | 6 + gcc/doc/gcc/contributors-to-gcc.rst | 6 + gcc/doc/gcc/copyright.rst | 25 + gcc/doc/gcc/exception-handling.rst | 15 + gcc/doc/gcc/extensions-to-the-c++-language.rst | 34 + .../backwards-compatibility.rst | 27 + .../c++-concepts.rst | 44 + .../c++-interface-and-implementation-pragmas.rst | 97 + ...cific-variable-function-and-type-attributes.rst | 95 + .../deprecated-features.rst | 43 + ...ter-from-a-bound-pointer-to-member-function.rst | 48 + .../function-multiversioning.rst | 65 + .../restricting-pointer-aliasing.rst | 52 + .../extensions-to-the-c++-language/type-traits.rst | 165 + .../vague-linkage.rst | 80 + .../when-is-a-volatile-c++-object-accessed.rst | 58 + .../wheres-the-template.rst | 131 + .../gcc/extensions-to-the-c-language-family.rst | 92 + .../128-bit-integers.rst | 18 + .../additional-floating-types.rst | 83 + .../alternate-keywords.rst | 46 + .../an-inline-function-is-as-fast-as-a-macro.rst | 126 + .../arithmetic-on-void-and-function-pointers.rst | 23 + .../arrays-of-length-zero.rst | 111 + .../arrays-of-variable-length.rst | 99 + .../attribute-syntax.rst | 259 ++ .../binary-constants-using-the-0b-prefix.rst | 29 + ...ns-for-memory-model-aware-atomic-operations.rst | 290 ++ ...o-perform-arithmetic-with-overflow-checking.rst | 102 + .../c++-style-comments.rst | 18 + .../case-ranges.rst | 43 + .../cast-to-a-union-type.rst | 69 + .../complex-numbers.rst | 122 + .../compound-literals.rst | 104 + .../conditionals-with-omitted-operands.rst | 39 + .../constructing-function-calls.rst | 125 + .../decimal-floating-types.rst | 47 + .../declaring-attributes-of-functions.rst | 109 + .../aarch64-function-attributes.rst | 192 + .../amd-gcn-function-attributes.rst | 93 + .../arc-function-attributes.rst | 88 + .../arm-function-attributes.rst | 168 + .../avr-function-attributes.rst | 120 + .../blackfin-function-attributes.rst | 91 + .../bpf-function-attributes.rst | 24 + .../c-sky-function-attributes.rst | 37 + .../common-function-attributes.rst | 1891 ++++++++ .../epiphany-function-attributes.rst | 82 + .../h8-300-function-attributes.rst | 39 + .../ia-64-function-attributes.rst | 36 + .../m32c-function-attributes.rst | 75 + .../m32r-d-function-attributes.rst | 42 + .../m68k-function-attributes.rst | 30 + .../mcore-function-attributes.rst | 24 + .../mep-function-attributes.rst | 53 + .../microblaze-function-attributes.rst | 46 + .../microsoft-windows-function-attributes.rst | 104 + .../mips-function-attributes.rst | 134 + .../msp430-function-attributes.rst | 103 + .../nds32-function-attributes.rst | 96 + .../nios-ii-function-attributes.rst | 42 + .../nvidia-ptx-function-attributes.rst | 22 + .../powerpc-function-attributes.rst | 225 + .../risc-v-function-attributes.rst | 43 + .../rl78-function-attributes.rst | 37 + .../rx-function-attributes.rst | 75 + .../s-390-function-attributes.rst | 52 + .../sh-function-attributes.rst | 101 + .../symbian-os-function-attributes.rst | 12 + .../v850-function-attributes.rst | 20 + .../visium-function-attributes.rst | 22 + .../x86-function-attributes.rst | 1020 ++++ .../xstormy16-function-attributes.rst | 20 + .../designated-initializers.rst | 147 + ...e-alignment-of-functions-types-or-variables.rst | 44 + .../dollar-signs-in-identifier-names.rst | 16 + .../double-word-integers.rst | 35 + .../enumerator-attributes.rst | 53 + .../fixed-point-types.rst | 128 + ...ecks-specific-to-particular-target-machines.rst | 47 + .../function-names-as-strings.rst | 71 + ...g-the-return-or-frame-address-of-a-function.rst | 97 + .../half-precision-floating-point.rst | 76 + .../hex-floats.rst | 30 + ...w-to-use-inline-assembly-language-in-c-code.rst | 1979 ++++++++ .../incomplete-enum-types.rst | 23 + .../label-attributes.rst | 65 + .../labels-as-values.rst | 86 + ...built-in-functions-for-atomic-memory-access.rst | 171 + .../locally-declared-labels.rst | 82 + .../macros-with-a-variable-number-of-arguments.rst | 68 + .../mixed-declarations-labels-and-code.rst | 27 + .../named-address-spaces.rst | 240 + .../nested-functions.rst | 132 + .../non-constant-initializers.rst | 23 + .../non-lvalue-arrays-may-have-subscripts.rst | 30 + .../nonlocal-gotos.rst | 62 + .../object-size-checking-built-in-functions.rst | 145 + .../other-built-in-functions-provided-by-gcc.rst | 1245 +++++ .../pointer-arguments-in-variadic-functions.rst | 22 + ...-to-arrays-with-qualifiers-work-as-expected.rst | 27 + .../pragmas-accepted-by-gcc.rst | 729 +++ ...ototypes-and-old-style-function-definitions.rst | 63 + .../referring-to-a-type-with-typeof.rst | 137 + .../slightly-looser-rules-for-escaped-newlines.rst | 23 + .../specifying-attributes-of-types.rst | 713 +++ .../specifying-attributes-of-variables.rst | 1187 +++++ .../statement-attributes.rst | 71 + .../statements-and-declarations-in-expressions.rst | 164 + .../structures-with-no-members.rst | 22 + .../support-for-offsetof.rst | 34 + .../target-builtins.rst | 53 + .../target-builtins/aarch64-built-in-functions.rst | 24 + .../target-builtins/alpha-built-in-functions.rst | 88 + .../altera-nios-ii-built-in-functions.rst | 118 + .../target-builtins/arc-built-in-functions.rst | 233 + .../arc-simd-built-in-functions.rst | 245 + .../arm-armv8-m-security-extensions.rst | 35 + .../arm-c-language-extensions-acle.rst | 30 + ...loating-point-status-and-control-intrinsics.rst | 17 + .../arm-iwmmxt-built-in-functions.rst | 159 + .../target-builtins/avr-built-in-functions.rst | 114 + .../basic-powerpc-built-in-functions.rst | 724 +++ .../blackfin-built-in-functions.rst | 20 + .../target-builtins/bpf-built-in-functions.rst | 100 + .../target-builtins/fr-v-built-in-functions.rst | 474 ++ .../mips-dsp-built-in-functions.rst | 312 ++ .../mips-loongson-built-in-functions.rst | 447 ++ .../target-builtins/mips-paired-single-support.rst | 45 + .../mips-simd-architecture-msa-support.rst | 812 ++++ .../target-builtins/msp430-built-in-functions.rst | 36 + .../target-builtins/nds32-built-in-functions.rst | 44 + .../other-mips-built-in-functions.rst | 27 + .../picochip-built-in-functions.rst | 45 + .../powerpc-altivec-vsx-built-in-functions.rst | 2181 +++++++++ .../powerpc-atomic-memory-operation-functions.rst | 68 + ...are-transactional-memory-built-in-functions.rst | 226 + ...c-matrix-multiply-assist-built-in-functions.rst | 104 + .../target-builtins/pru-built-in-functions.rst | 34 + .../target-builtins/risc-v-built-in-functions.rst | 16 + .../target-builtins/rx-built-in-functions.rst | 122 + .../s-390-system-z-built-in-functions.rst | 121 + .../target-builtins/sh-built-in-functions.rst | 50 + .../sparc-vis-built-in-functions.rst | 226 + .../target-builtins/ti-c6x-built-in-functions.rst | 43 + .../target-builtins/x86-built-in-functions.rst | 1698 +++++++ .../x86-control-flow-protection-intrinsics.rst | 50 + .../x86-transactional-memory-intrinsics.rst | 102 + .../the-character-esc-in-constants.rst | 12 + .../thread-local-storage.rst | 219 + .../unnamed-structure-and-union-fields.rst | 86 + ...tor-instructions-through-built-in-functions.rst | 285 ++ .../when-is-a-volatile-object-accessed.rst | 86 + ...y-model-extensions-for-transactional-memory.rst | 38 + gcc/doc/gcc/funding.rst | 6 + gcc/doc/gcc/gcc-command-options.rst | 67 + gcc/doc/gcc/gcc-command-options/c++-modules.rst | 352 ++ .../gcc-command-options/compiling-c++-programs.rst | 42 + gcc/doc/gcc/gcc-command-options/description.rst | 73 + .../environment-variables-affecting-gcc.rst | 163 + .../gcc-command-options/gcc-developer-options.rst | 1174 +++++ .../machine-dependent-options.rst | 92 + .../machine-dependent-options/aarch64-options.rst | 550 +++ .../adapteva-epiphany-options.rst | 163 + .../machine-dependent-options/amd-gcn-options.rst | 58 + .../machine-dependent-options/arc-options.rst | 759 +++ .../machine-dependent-options/arm-options.rst | 1037 +++++ .../machine-dependent-options/avr-mmcu.rst | 97 + .../machine-dependent-options/avr-options.rst | 543 +++ .../machine-dependent-options/blackfin-options.rst | 227 + .../machine-dependent-options/c-sky-options.rst | 193 + .../machine-dependent-options/c6x-options.rst | 55 + .../machine-dependent-options/cris-options.rst | 102 + .../machine-dependent-options/darwin-options.rst | 224 + .../dec-alpha-options.rst | 274 ++ .../machine-dependent-options/ebpf-options.rst | 94 + .../machine-dependent-options/fr30-options.rst | 27 + .../machine-dependent-options/frv-options.rst | 279 ++ .../machine-dependent-options/ft32-options.rst | 44 + .../gnu-linux-options.rst | 56 + .../machine-dependent-options/h8-300-options.rst | 64 + .../machine-dependent-options/hppa-options.rst | 245 + .../machine-dependent-options/ia-64-options.rst | 261 ++ .../ibm-rs-6000-and-powerpc-options.rst | 1017 ++++ .../machine-dependent-options/lm32-options.rst | 35 + .../loongarch-options.rst | 191 + .../machine-dependent-options/m32c-options.rst | 38 + .../machine-dependent-options/m32r-d-options.rst | 137 + .../machine-dependent-options/m680x0-options.rst | 407 ++ .../machine-dependent-options/mcore-options.rst | 66 + .../machine-dependent-options/mep-options.rst | 167 + .../microblaze-options.rst | 121 + .../machine-dependent-options/mips-options.rst | 986 ++++ .../machine-dependent-options/mmix-options.rst | 75 + .../machine-dependent-options/mn10300-options.rst | 93 + .../machine-dependent-options/moxie-options.rst | 31 + .../machine-dependent-options/msp430-options.rst | 189 + .../machine-dependent-options/nds32-options.rst | 116 + .../machine-dependent-options/nios-ii-options.rst | 363 ++ .../nvidia-ptx-options.rst | 98 + .../machine-dependent-options/openrisc-options.rst | 95 + .../options-for-system-v.rst | 43 + .../machine-dependent-options/pdp-11-options.rst | 73 + .../machine-dependent-options/picochip-options.rst | 55 + .../machine-dependent-options/powerpc-options.rst | 15 + .../machine-dependent-options/pru-options.rst | 63 + .../machine-dependent-options/risc-v-options.rst | 216 + .../machine-dependent-options/rl78-options.rst | 91 + .../machine-dependent-options/rx-options.rst | 209 + .../s-390-and-zseries-options.rst | 244 + .../machine-dependent-options/score-options.rst | 51 + .../machine-dependent-options/sh-options.rst | 444 ++ .../solaris-2-options.rst | 42 + .../machine-dependent-options/sparc-options.rst | 388 ++ .../machine-dependent-options/v850-options.rst | 207 + .../machine-dependent-options/vax-options.rst | 35 + .../machine-dependent-options/visium-options.rst | 73 + .../machine-dependent-options/vms-options.rst | 38 + .../machine-dependent-options/vxworks-options.rst | 45 + .../machine-dependent-options/x86-options.rst | 1620 +++++++ .../x86-windows-options.rst | 95 + .../xstormy16-options.rst | 19 + .../machine-dependent-options/xtensa-options.rst | 138 + .../machine-dependent-options/zseries-options.rst | 15 + gcc/doc/gcc/gcc-command-options/option-summary.rst | 1527 ++++++ .../options-controlling-c++-dialect.rst | 2133 +++++++++ .../options-controlling-c-dialect.rst | 544 +++ ...ling-objective-c-and-objective-c++-dialects.rst | 316 ++ .../options-controlling-the-kind-of-output.rst | 732 +++ .../options-controlling-the-preprocessor.rst | 79 + .../options-for-code-generation-conventions.rst | 713 +++ .../options-for-debugging-your-program.rst | 471 ++ .../options-for-directory-search.rst | 102 + .../gcc-command-options/options-for-linking.rst | 407 ++ .../options-that-control-optimization.rst | 4857 +++++++++++++++++++ .../options-that-control-static-analysis.rst | 1067 +++++ ...s-to-control-diagnostic-messages-formatting.rst | 899 ++++ .../options-to-request-or-suppress-warnings.rst | 4866 ++++++++++++++++++++ .../passing-options-to-the-assembler.rst | 27 + .../program-instrumentation-options.rst | 1111 +++++ ...bprocesses-and-the-switches-to-pass-to-them.rst | 687 +++ .../using-precompiled-headers.rst | 132 + gcc/doc/gcc/gcc.rst | 47 + gcc/doc/gcc/gcov-dump.rst | 70 + gcc/doc/gcc/gcov-tool.rst | 209 + gcc/doc/gcc/gcov.rst | 53 + .../gcov/brief-description-of-gcov-data-files.rst | 33 + ...-file-relocation-to-support-cross-profiling.rst | 43 + gcc/doc/gcc/gcov/introduction-to-gcov.rst | 62 + gcc/doc/gcc/gcov/invoking-gcov.rst | 656 +++ ...-test-coverage-in-freestanding-environments.rst | 391 ++ .../gcc/gcov/using-gcov-with-gcc-optimization.rst | 86 + gcc/doc/gcc/general-public-license-3.rst | 6 + gcc/doc/gcc/gnu-free-documentation-license.rst | 6 + gcc/doc/gcc/gnu-objective-c-features.rst | 27 + .../compatibilityalias.rst | 26 + .../constant-string-objects.rst | 64 + .../gcc/gnu-objective-c-features/exceptions.rst | 79 + .../gnu-objective-c-features/fast-enumeration.rst | 221 + .../garbage-collection.rst | 81 + .../gnu-objective-c-runtime-api.rst | 98 + .../load-executing-code-before-main.rst | 141 + .../messaging-with-the-gnu-objective-c-runtime.rst | 145 + .../gnu-objective-c-features/synchronization.rst | 36 + .../gcc/gnu-objective-c-features/type-encoding.rst | 280 ++ gcc/doc/gcc/gnu.rst | 1 + gcc/doc/gcc/have-you-found-a-bug.rst | 62 + gcc/doc/gcc/how-and-where-to-report-bugs.rst | 13 + gcc/doc/gcc/how-to-get-help-with-gcc.rst | 26 + gcc/doc/gcc/index.rst | 40 + gcc/doc/gcc/indices-and-tables.rst | 1 + gcc/doc/gcc/known-causes-of-trouble-with-gcc.rst | 32 + .../actual-bugs-we-havent-fixed-yet.rst | 14 + .../certain-changes-we-dont-want-to-make.rst | 236 + .../common-misunderstandings-with-gnu-c.rst | 296 ++ .../disappointments-and-misunderstandings.rst | 102 + .../fixed-header-files.rst | 39 + .../incompatibilities-of-gcc.rst | 233 + .../interoperation.rst | 153 + .../standard-libraries.rst | 33 + .../warning-messages-and-error-messages.rst | 46 + .../gcc/language-standards-supported-by-gcc.rst | 23 + .../c++-language.rst | 71 + .../c-language.rst | 139 + .../d-language.rst | 11 + .../go-language.rst | 10 + .../objective-c-and-objective-c++-languages.rst | 62 + .../references-for-other-languages.rst | 13 + gcc/doc/gcc/lto-dump.rst | 117 + .../gcc/programming-languages-supported-by-gcc.rst | 54 + gcc/doc/gcc/reporting-bugs.rst | 23 + .../analysis-and-optimization-of-gimple-tuples.rst | 44 + .../alias-analysis.rst | 104 + .../annotations.rst | 17 + .../memory-model.rst | 34 + .../ssa-operands.rst | 388 ++ .../static-single-assignment.rst | 259 ++ .../analysis-and-representation-of-loops.rst | 27 + .../data-dependency-analysis.rst | 135 + .../iv-analysis-on-rtl.rst | 55 + .../loop-closed-ssa-form.rst | 47 + .../loop-manipulation.rst | 58 + .../loop-querying.rst | 81 + .../loop-representation.rst | 137 + .../number-of-iterations-analysis.rst | 85 + .../scalar-evolutions.rst | 71 + gcc/doc/gccint/analyzer-internals.rst | 419 ++ gcc/doc/gccint/collect2.rst | 77 + gcc/doc/gccint/conf.py | 24 + gcc/doc/gccint/contributing-to-gcc-development.rst | 6 + gcc/doc/gccint/contributors-to-gcc.rst | 6 + gcc/doc/gccint/control-flow-graph.rst | 43 + gcc/doc/gccint/control-flow-graph/basic-blocks.rst | 141 + gcc/doc/gccint/control-flow-graph/edges.rst | 241 + .../control-flow-graph/liveness-information.rst | 48 + .../control-flow-graph/maintaining-the-cfg.rst | 145 + .../control-flow-graph/profile-information.rst | 112 + gcc/doc/gccint/copyright.rst | 25 + gcc/doc/gccint/debugging-the-analyzer.rst | 141 + gcc/doc/gccint/funding.rst | 6 + gcc/doc/gccint/gcc-and-portability.rst | 41 + gcc/doc/gccint/general-public-license-3.rst | 6 + gcc/doc/gccint/generic.rst | 47 + gcc/doc/gccint/generic/attributes-in-trees.rst | 35 + gcc/doc/gccint/generic/c-and-c++-trees.rst | 886 ++++ gcc/doc/gccint/generic/declarations.rst | 346 ++ gcc/doc/gccint/generic/deficiencies.rst | 14 + gcc/doc/gccint/generic/expressions.rst | 910 ++++ gcc/doc/gccint/generic/functions.rst | 212 + .../gccint/generic/language-dependent-trees.rst | 25 + gcc/doc/gccint/generic/overview.rst | 213 + gcc/doc/gccint/generic/statements.rst | 516 +++ gcc/doc/gccint/generic/types.rst | 299 ++ gcc/doc/gccint/gimple-api.rst | 47 + gcc/doc/gccint/gimple.rst | 88 + .../gimple/adding-a-new-gimple-statement-code.rst | 36 + .../class-hierarchy-of-gimple-statements.rst | 150 + gcc/doc/gccint/gimple/exception-handling.rst | 46 + gcc/doc/gccint/gimple/gimple-instruction-set.rst | 106 + gcc/doc/gccint/gimple/gimple-sequences.rst | 94 + .../gimple/manipulating-gimple-statements.rst | 176 + gcc/doc/gccint/gimple/operands.rst | 319 ++ gcc/doc/gccint/gimple/sequence-iterators.rst | 223 + .../gimple/statement-and-operand-traversals.rst | 62 + gcc/doc/gccint/gimple/temporaries.rst | 43 + gcc/doc/gccint/gimple/tuple-representation.rst | 242 + gcc/doc/gccint/gimple/tuple-specific-accessors.rst | 44 + .../gimple/tuple-specific-accessors/gimpleasm.rst | 66 + .../tuple-specific-accessors/gimpleassign.rst | 126 + .../gimple/tuple-specific-accessors/gimplebind.rst | 56 + .../gimple/tuple-specific-accessors/gimplecall.rst | 116 + .../tuple-specific-accessors/gimplecatch.rst | 37 + .../gimple/tuple-specific-accessors/gimplecond.rst | 80 + .../tuple-specific-accessors/gimpledebug.rst | 106 + .../tuple-specific-accessors/gimpleehfilter.rst | 45 + .../gimple/tuple-specific-accessors/gimplegoto.rst | 21 + .../tuple-specific-accessors/gimplelabel.rst | 23 + .../gimple/tuple-specific-accessors/gimplenop.rst | 17 + .../gimpleompatomicload.rst | 31 + .../gimpleompatomicstore.rst | 22 + .../tuple-specific-accessors/gimpleompcontinue.rst | 43 + .../tuple-specific-accessors/gimpleompcritical.rst | 28 + .../tuple-specific-accessors/gimpleompfor.rst | 97 + .../tuple-specific-accessors/gimpleompmaster.rst | 14 + .../tuple-specific-accessors/gimpleompordered.rst | 16 + .../tuple-specific-accessors/gimpleompparallel.rst | 76 + .../tuple-specific-accessors/gimpleompreturn.rst | 23 + .../tuple-specific-accessors/gimpleompsection.rst | 24 + .../tuple-specific-accessors/gimpleompsections.rst | 48 + .../tuple-specific-accessors/gimpleompsingle.rst | 28 + .../gimple/tuple-specific-accessors/gimplephi.rst | 41 + .../gimple/tuple-specific-accessors/gimpleresx.rst | 24 + .../tuple-specific-accessors/gimplereturn.rst | 21 + .../tuple-specific-accessors/gimpleswitch.rst | 52 + .../gimple/tuple-specific-accessors/gimpletry.rst | 51 + .../gimplewithcleanupexpr.rst | 30 + gcc/doc/gccint/gnu-free-documentation-license.rst | 6 + gcc/doc/gccint/guidelines-for-diagnostics.rst | 598 +++ gcc/doc/gccint/guidelines-for-options.rst | 13 + gcc/doc/gccint/host-common.rst | 57 + gcc/doc/gccint/host-configuration.rst | 32 + gcc/doc/gccint/host-filesystem.rst | 103 + gcc/doc/gccint/host-makefile-fragments.rst | 14 + gcc/doc/gccint/host-misc.rst | 70 + gcc/doc/gccint/index.rst | 51 + gcc/doc/gccint/indices-and-tables.rst | 1 + gcc/doc/gccint/interfacing-to-gcc-output.rst | 71 + gcc/doc/gccint/introduction.rst | 26 + gcc/doc/gccint/language-front-ends-in-gcc.rst | 39 + gcc/doc/gccint/link-time-optimization.rst | 33 + .../link-time-optimization/design-overview.rst | 123 + .../internal-flags-controlling-lto1.rst | 42 + .../link-time-optimization/lto-file-sections.rst | 110 + .../using-summary-information-in-ipa-passes.rst | 206 + ...tions-linker-plugin-and-symbol-visibilities.rst | 91 + gcc/doc/gccint/machine-descriptions.rst | 49 + .../c-statements-for-assembler-output.rst | 122 + .../canonicalization-of-instructions.rst | 152 + .../machine-descriptions/conditional-execution.rst | 98 + .../machine-descriptions/constant-definitions.rst | 185 + .../defining-how-to-split-instructions.rst | 374 ++ .../defining-jump-instruction-patterns.rst | 37 + .../defining-looping-instruction-patterns.rst | 134 + .../defining-rtl-sequences-for-code-generation.rst | 206 + .../everything-about-instruction-patterns.rst | 106 + .../machine-descriptions/example-of-defineinsn.rst | 54 + .../including-patterns-in-machine-descriptions.rst | 70 + .../instruction-attributes.rst | 1248 +++++ .../interdependence-of-patterns.rst | 43 + gcc/doc/gccint/machine-descriptions/iterators.rst | 543 +++ .../machine-specific-peephole-optimizers.rst | 330 ++ .../machine-descriptions/operand-constraints.rst | 426 ++ .../output-templates-and-operand-substitution.rst | 99 + ...view-of-how-the-machine-description-is-used.rst | 47 + gcc/doc/gccint/machine-descriptions/predicates.rst | 343 ++ .../gccint/machine-descriptions/rtl-template.rst | 255 + .../rtl-templates-transformations.rst | 225 + .../standard-pattern-names-for-generation.rst | 3413 ++++++++++++++ .../when-the-order-of-patterns-matters.rst | 29 + gcc/doc/gccint/makefile-fragments.rst | 37 + gcc/doc/gccint/match-and-simplify.rst | 34 + .../memory-management-and-type-information.rst | 103 + .../how-to-invoke-the-garbage-collector.rst | 36 + .../marking-roots-for-the-garbage-collector.rst | 28 + .../source-files-containing-type-information.rst | 60 + .../support-for-inheritance.rst | 59 + ...pport-for-user-provided-gc-marking-routines.rst | 121 + .../the-inside-of-a-gty.rst | 324 ++ .../troubleshooting-the-garbage-collector.rst | 27 + gcc/doc/gccint/option-file-format.rst | 175 + gcc/doc/gccint/option-properties.rst | 376 ++ gcc/doc/gccint/option-specification-files.rst | 21 + .../gccint/passes-and-files-of-the-compiler.rst | 27 + .../gimplification-pass.rst | 44 + .../inter-procedural-optimization-passes.rst | 269 ++ .../optimization-info.rst | 262 ++ .../parsing-pass.rst | 80 + .../pass-manager.rst | 42 + .../rtl-passes.rst | 275 ++ .../tree-ssa-passes.rst | 477 ++ gcc/doc/gccint/plugins.rst | 35 + gcc/doc/gccint/plugins/building-gcc-plugins.rst | 97 + .../controlling-which-passes-are-being-run.rst | 16 + .../plugins/giving-information-about-a-plugin.rst | 24 + .../interacting-with-the-gcc-garbage-collector.rst | 37 + .../plugins/interacting-with-the-pass-manager.rst | 57 + .../plugins/keeping-track-of-available-passes.rst | 17 + gcc/doc/gccint/plugins/loading-plugins.rst | 31 + gcc/doc/gccint/plugins/plugin-api.rst | 213 + .../recording-information-about-pass-execution.rst | 20 + .../registering-custom-attributes-or-pragmas.rst | 73 + gcc/doc/gccint/rtl-representation.rst | 48 + .../rtl-representation/access-to-operands.rst | 73 + .../access-to-special-operands.rst | 188 + .../assembler-instructions-as-expressions.rst | 45 + gcc/doc/gccint/rtl-representation/bit-fields.rst | 48 + .../rtl-representation/comparison-operations.rst | 112 + .../constant-expression-types.rst | 313 ++ gcc/doc/gccint/rtl-representation/conversions.rst | 152 + gcc/doc/gccint/rtl-representation/declarations.rst | 27 + .../embedded-side-effects-on-addresses.rst | 100 + .../flags-in-an-rtl-expression.rst | 447 ++ gcc/doc/gccint/rtl-representation/insns.rst | 624 +++ .../gccint/rtl-representation/machine-modes.rst | 635 +++ .../on-the-side-ssa-form-for-rtl.rst | 748 +++ gcc/doc/gccint/rtl-representation/reading-rtl.rst | 28 + .../rtl-representation/registers-and-memory.rst | 451 ++ .../rtl-representation/rtl-classes-and-formats.rst | 192 + .../rtl-expressions-for-arithmetic.rst | 310 ++ .../gccint/rtl-representation/rtl-object-types.rst | 84 + .../rtl-representation-of-function-call-insns.rst | 72 + .../rtl-representation/side-effect-expressions.rst | 374 ++ .../structure-sharing-assumptions.rst | 99 + .../variable-location-debug-information-in-rtl.rst | 64 + .../rtl-representation/vector-operations.rst | 60 + .../sizes-and-offsets-as-runtime-invariants.rst | 51 + .../alignment-of-polyints.rst | 84 + .../arithmetic-on-polyints.rst | 178 + .../comparisons-involving-polyint.rst | 324 ++ .../computing-bounds-on-polyints.rst | 34 + .../consequences-of-using-polyint.rst | 55 + .../converting-polyints.rst | 91 + .../guidelines-for-using-polyint.rst | 119 + .../miscellaneous-polyint-routines.rst | 16 + .../overview-of-polyint.rst | 78 + .../source-tree-structure-and-build-system.rst | 21 + .../configure-terms-and-history.rst | 64 + .../the-gcc-subdirectory.rst | 28 + .../anatomy-of-a-language-front-end.rst | 281 ++ .../anatomy-of-a-target-back-end.rst | 116 + .../build-system-in-the-gcc-directory.rst | 14 + .../building-documentation.rst | 247 + .../configuration-in-the-gcc-directory.rst | 127 + .../headers-installed-by-gcc.rst | 50 + ...e-files-and-headers-under-the-gcc-directory.rst | 15 + .../the-gcc-subdirectory/makefile-targets.rst | 195 + .../the-gcc-subdirectory/subdirectories-of-gcc.rst | 55 + .../top-level-source-directory.rst | 135 + .../gccint/standard-header-file-directories.rst | 35 + gcc/doc/gccint/static-analyzer.rst | 19 + gcc/doc/gccint/target-macros.rst | 60 + .../adding-support-for-named-address-spaces.rst | 163 + gcc/doc/gccint/target-macros/addressing-modes.rst | 824 ++++ .../adjusting-the-instruction-scheduler.rst | 660 +++ .../gccint/target-macros/anchored-addresses.rst | 92 + .../gccint/target-macros/c++-abi-parameters.rst | 164 + .../gccint/target-macros/condition-code-status.rst | 210 + .../controlling-debugging-information-format.rst | 306 ++ .../controlling-the-compilation-driver-gcc.rst | 482 ++ .../cross-compilation-and-floating-point.rst | 73 + gcc/doc/gccint/target-macros/d-abi-parameters.rst | 111 + ...ning-coprocessor-specifics-for-mips-targets.rst | 35 + ...ata-structures-for-per-function-information.rst | 62 + .../defining-target-specific-uses-of-attribute.rst | 319 ++ .../defining-the-output-assembler-language.rst | 27 + .../assembler-commands-for-alignment.rst | 95 + .../assembler-commands-for-exception-regions.rst | 188 + .../how-initialization-functions-are-handled.rst | 122 + .../macros-controlling-initialization-routines.rst | 182 + .../output-and-generation-of-labels.rst | 586 +++ .../output-of-assembler-instructions.rst | 252 + .../output-of-data.rst | 191 + .../output-of-dispatch-tables.rst | 171 + .../output-of-uninitialized-variables.rst | 105 + .../the-overall-framework-of-an-assembler-file.rst | 287 ++ .../describing-relative-costs-of-operations.rst | 528 +++ ...ividing-the-output-into-sections-texts-data.rst | 445 ++ gcc/doc/gccint/target-macros/emulating-tls.rst | 125 + .../implementing-the-varargs-macros.rst | 192 + .../implicit-calls-to-library-routines.rst | 141 + .../layout-of-source-language-data-types.rst | 355 ++ .../target-macros/miscellaneous-parameters.rst | 1718 +++++++ .../target-macros/mode-switching-instructions.rst | 121 + ...rs-for-precompiled-header-validity-checking.rst | 63 + .../target-macros/position-independent-code.rst | 53 + gcc/doc/gccint/target-macros/register-classes.rst | 801 ++++ gcc/doc/gccint/target-macros/register-usage.rst | 563 +++ .../run-time-target-specification.rst | 273 ++ .../stack-layout-and-calling-conventions.rst | 35 + .../basic-stack-layout.rst | 304 ++ .../caller-saves-register-allocation.rst | 21 + .../eliminating-frame-pointer-and-arg-pointer.rst | 102 + .../exception-handling-support.rst | 137 + .../function-entry-and-exit.rst | 265 ++ .../generating-code-for-profiling.rst | 61 + .../how-large-values-are-returned.rst | 132 + .../how-scalar-function-values-are-returned.rst | 166 + .../miscellaneous-register-hooks.rst | 26 + .../passing-arguments-in-registers.rst | 633 +++ .../passing-function-arguments-on-the-stack.rst | 193 + .../permitting-tail-calls.rst | 60 + .../registers-that-address-the-stack-frame.rst | 198 + .../shrink-wrapping-separate-components.rst | 93 + .../specifying-how-stack-checking-is-done.rst | 118 + .../stack-smashing-protection.rst | 75 + gcc/doc/gccint/target-macros/storage-layout.rst | 729 +++ .../target-macros/support-for-nested-functions.rst | 222 + .../target-macros/the-global-targetm-variable.rst | 65 + gcc/doc/gccint/target-makefile-fragments.rst | 245 + gcc/doc/gccint/testsuites.rst | 31 + .../gccint/testsuites/ada-language-testsuites.rst | 38 + .../gccint/testsuites/c-language-testsuites.rst | 113 + .../directives-used-within-dejagnu-tests.rst | 19 + .../commands-for-use-in-dg-final.rst | 291 ++ .../features-for-dg-add-options.rst | 122 + .../keywords-describing-target-attributes.rst | 1524 ++++++ .../selecting-targets-to-which-a-test-applies.rst | 106 + .../syntax-and-descriptions-of-test-directives.rst | 311 ++ .../variants-of-dg-require-support.rst | 83 + .../testsuites/idioms-used-in-testsuite-code.rst | 84 + .../support-for-testing-binary-compatibility.rst | 109 + .../gccint/testsuites/support-for-testing-gcov.rst | 72 + .../support-for-testing-gimple-passes.rst | 55 + ...support-for-testing-link-time-optimizations.rst | 46 + ...-for-testing-profile-directed-optimizations.rst | 51 + .../testsuites/support-for-testing-rtl-passes.rst | 48 + ...-for-torture-testing-using-multiple-options.rst | 52 + .../gccint/the-gcc-low-level-runtime-library.rst | 50 + ...independent-routines-for-exception-handling.rst | 42 + .../miscellaneous-runtime-library-routines.rst | 59 + ...utines-for-decimal-floating-point-emulation.rst | 312 ++ ...utines-for-fixed-point-fractional-emulation.rst | 1432 ++++++ .../routines-for-floating-point-emulation.rst | 283 ++ .../routines-for-integer-arithmetic.rst | 183 + gcc/doc/gccint/the-language.rst | 384 ++ gcc/doc/gccint/user-experience-guidelines.rst | 30 + gcc/doc/install/binaries.rst | 54 + gcc/doc/install/building.rst | 67 + .../install/building/building-a-cross-compiler.rst | 74 + .../building/building-a-native-compiler.rst | 191 + gcc/doc/install/building/building-in-parallel.rst | 15 + .../install/building/building-the-ada-compiler.rst | 9 + .../install/building/building-the-d-compiler.rst | 9 + .../building/building-with-profile-feedback.rst | 34 + gcc/doc/install/conf.py | 24 + gcc/doc/install/configuration.rst | 2098 +++++++++ gcc/doc/install/copyright.rst | 24 + gcc/doc/install/downloading-gcc.rst | 42 + gcc/doc/install/final-installation.rst | 128 + gcc/doc/install/gnu-free-documentation-license.rst | 6 + ...-target-specific-installation-notes-for-gcc.rst | 1336 ++++++ ...can-you-run-the-testsuite-on-selected-tests.rst | 46 + gcc/doc/install/how-to-interpret-test-results.rst | 32 + gcc/doc/install/index.rst | 27 + gcc/doc/install/indices-and-tables.rst | 1 + gcc/doc/install/installing-gcc.rst | 39 + ...ing-options-and-running-multiple-testsuites.rst | 74 + gcc/doc/install/prerequisites.rst | 319 ++ gcc/doc/install/submitting-test-results.rst | 22 + gcc/doc/install/testing.rst | 69 + .../code-that-interacts-with-the-user.rst | 15 + .../doc/gfc-internals/command-line-options.rst | 30 + gcc/fortran/doc/gfc-internals/conf.py | 24 + gcc/fortran/doc/gfc-internals/copyright.rst | 25 + gcc/fortran/doc/gfc-internals/error-handling.rst | 75 + .../doc/gfc-internals/frontend-data-structures.rst | 23 + ...-the-intermediate-language-for-later-stages.rst | 24 + .../accessing-declarations.rst | 16 + .../basic-data-structures.rst | 67 + .../converting-expressions-to-tree.rst | 48 + .../translating-statements.rst | 14 + gcc/fortran/doc/gfc-internals/gfccode.rst | 146 + gcc/fortran/doc/gfc-internals/gfcexpr.rst | 156 + .../gnu-free-documentation-license.rst | 6 + gcc/fortran/doc/gfc-internals/index.rst | 24 + .../doc/gfc-internals/indices-and-tables.rst | 1 + .../internals-of-fortran-2003-oop-features.rst | 15 + gcc/fortran/doc/gfc-internals/introduction.rst | 32 + .../doc/gfc-internals/symbol-versioning.rst | 63 + .../the-libgfortran-runtime-library.rst | 14 + .../doc/gfc-internals/type-bound-operators.rst | 33 + .../doc/gfc-internals/type-bound-procedures.rst | 101 + gcc/fortran/doc/gfortran/about-gnu-fortran.rst | 115 + gcc/fortran/doc/gfortran/coarray-programming.rst | 17 + .../doc/gfortran/compiler-characteristics.rst | 27 + .../compiler-characteristics/asynchronous-i-o.rst | 21 + .../data-consistency-and-durability.rst | 80 + .../evaluation-of-logical-expressions.rst | 18 + ...file-format-of-unformatted-sequential-files.rst | 63 + .../file-operations-on-symbolic-links.rst | 28 + ...pened-without-an-explicit-action=-specifier.rst | 23 + ...nternal-representation-of-logical-variables.rst | 24 + .../kind-type-parameters.rst | 54 + ...-and-min-intrinsics-with-real-nan-arguments.rst | 21 + .../thread-safety-of-the-runtime-library.rst | 53 + gcc/fortran/doc/gfortran/conf.py | 30 + gcc/fortran/doc/gfortran/contributing.rst | 28 + .../doc/gfortran/contributors-to-gnu-fortran.rst | 109 + gcc/fortran/doc/gfortran/copyright.rst | 25 + .../extensions-implemented-in-gnu-fortran.rst | 1535 ++++++ .../extensions-not-implemented-in-gnu-fortran.rst | 186 + gcc/fortran/doc/gfortran/extensions.rst | 24 + .../doc/gfortran/function-abi-documentation.rst | 1526 ++++++ gcc/fortran/doc/gfortran/funding.rst | 6 + .../doc/gfortran/general-public-license-3.rst | 6 + gcc/fortran/doc/gfortran/gnu-fortran-and-gcc.rst | 48 + .../doc/gfortran/gnu-fortran-command-options.rst | 33 + .../gnu-fortran-command-options/description.rst | 39 + .../enable-and-customize-preprocessing.rst | 298 ++ .../environment-variables-affecting-gfortran.rst | 24 + .../influencing-runtime-behavior.rst | 67 + .../influencing-the-linking-step.rst | 37 + .../gnu-fortran-command-options/option-summary.rst | 104 + .../options-controlling-fortran-dialect.rst | 411 ++ .../options-for-code-generation-conventions.rst | 583 +++ ...s-for-debugging-your-program-or-gnu-fortran.rst | 134 + .../options-for-directory-search.rst | 54 + ...s-for-interoperability-with-other-languages.rst | 63 + ...-to-request-or-suppress-errors-and-warnings.rst | 411 ++ .../gfortran/gnu-fortran-compiler-directives.rst | 174 + .../gfortran/gnu-free-documentation-license.rst | 6 + gcc/fortran/doc/gfortran/index.rst | 56 + gcc/fortran/doc/gfortran/indices-and-tables.rst | 1 + .../doc/gfortran/interoperability-with-c.rst | 413 ++ gcc/fortran/doc/gfortran/intrinsic-modules.rst | 20 + ...eexceptions-ieeearithmetic-and-ieeefeatures.rst | 29 + .../doc/gfortran/intrinsic-modules/isocbinding.rst | 227 + .../gfortran/intrinsic-modules/isofortranenv.rst | 116 + .../intrinsic-modules/openacc-module-openacc.rst | 27 + .../openmp-modules-omplib-and-omplibkinds.rst | 161 + gcc/fortran/doc/gfortran/intrinsic-procedures.rst | 299 ++ .../doc/gfortran/intrinsic-procedures/abort.rst | 44 + .../doc/gfortran/intrinsic-procedures/abs.rst | 117 + .../doc/gfortran/intrinsic-procedures/access.rst | 61 + .../doc/gfortran/intrinsic-procedures/achar.rst | 56 + .../doc/gfortran/intrinsic-procedures/acos.rst | 73 + .../doc/gfortran/intrinsic-procedures/acosd.rst | 74 + .../doc/gfortran/intrinsic-procedures/acosh.rst | 70 + .../doc/gfortran/intrinsic-procedures/adjustl.rst | 48 + .../doc/gfortran/intrinsic-procedures/adjustr.rst | 48 + .../doc/gfortran/intrinsic-procedures/aimag.rst | 81 + .../doc/gfortran/intrinsic-procedures/aint.rst | 78 + .../doc/gfortran/intrinsic-procedures/alarm.rst | 59 + .../doc/gfortran/intrinsic-procedures/all.rst | 61 + .../gfortran/intrinsic-procedures/allocated.rst | 49 + .../doc/gfortran/intrinsic-procedures/and.rst | 60 + .../doc/gfortran/intrinsic-procedures/anint.rst | 76 + .../doc/gfortran/intrinsic-procedures/any.rst | 61 + .../doc/gfortran/intrinsic-procedures/asin.rst | 73 + .../doc/gfortran/intrinsic-procedures/asind.rst | 74 + .../doc/gfortran/intrinsic-procedures/asinh.rst | 70 + .../gfortran/intrinsic-procedures/associated.rst | 74 + .../doc/gfortran/intrinsic-procedures/atan.rst | 80 + .../doc/gfortran/intrinsic-procedures/atan2.rst | 85 + .../doc/gfortran/intrinsic-procedures/atan2d.rst | 85 + .../doc/gfortran/intrinsic-procedures/atand.rst | 80 + .../doc/gfortran/intrinsic-procedures/atanh.rst | 70 + .../gfortran/intrinsic-procedures/atomicadd.rst | 60 + .../gfortran/intrinsic-procedures/atomicand.rst | 60 + .../gfortran/intrinsic-procedures/atomiccas.rst | 67 + .../gfortran/intrinsic-procedures/atomicdefine.rst | 62 + .../intrinsic-procedures/atomicfetchadd.rst | 65 + .../intrinsic-procedures/atomicfetchand.rst | 64 + .../intrinsic-procedures/atomicfetchor.rst | 64 + .../intrinsic-procedures/atomicfetchxor.rst | 64 + .../doc/gfortran/intrinsic-procedures/atomicor.rst | 60 + .../gfortran/intrinsic-procedures/atomicref.rst | 68 + .../gfortran/intrinsic-procedures/atomicxor.rst | 60 + .../gfortran/intrinsic-procedures/backtrace.rst | 34 + .../doc/gfortran/intrinsic-procedures/besselj0.rst | 64 + .../doc/gfortran/intrinsic-procedures/besselj1.rst | 64 + .../doc/gfortran/intrinsic-procedures/besseljn.rst | 85 + .../doc/gfortran/intrinsic-procedures/bessely0.rst | 62 + .../doc/gfortran/intrinsic-procedures/bessely1.rst | 62 + .../doc/gfortran/intrinsic-procedures/besselyn.rst | 85 + .../doc/gfortran/intrinsic-procedures/bge.rst | 42 + .../doc/gfortran/intrinsic-procedures/bgt.rst | 41 + .../doc/gfortran/intrinsic-procedures/bitsize.rst | 44 + .../doc/gfortran/intrinsic-procedures/ble.rst | 42 + .../doc/gfortran/intrinsic-procedures/blt.rst | 41 + .../doc/gfortran/intrinsic-procedures/btest.rst | 89 + .../gfortran/intrinsic-procedures/cassociated.rst | 54 + .../doc/gfortran/intrinsic-procedures/ceiling.rst | 51 + .../gfortran/intrinsic-procedures/cfpointer.rst | 63 + .../intrinsic-procedures/cfprocpointer.rst | 64 + .../doc/gfortran/intrinsic-procedures/cfunloc.rst | 64 + .../doc/gfortran/intrinsic-procedures/char.rst | 71 + .../doc/gfortran/intrinsic-procedures/chdir.rst | 51 + .../doc/gfortran/intrinsic-procedures/chmod.rst | 70 + .../doc/gfortran/intrinsic-procedures/cloc.rst | 51 + .../doc/gfortran/intrinsic-procedures/cmplx.rst | 61 + .../gfortran/intrinsic-procedures/cobroadcast.rst | 65 + .../doc/gfortran/intrinsic-procedures/comax.rst | 66 + .../doc/gfortran/intrinsic-procedures/comin.rst | 66 + .../intrinsic-procedures/commandargumentcount.rst | 43 + .../intrinsic-procedures/compileroptions.rst | 48 + .../intrinsic-procedures/compilerversion.rst | 47 + .../doc/gfortran/intrinsic-procedures/complex.rst | 50 + .../doc/gfortran/intrinsic-procedures/conjg.rst | 63 + .../doc/gfortran/intrinsic-procedures/coreduce.rst | 94 + .../doc/gfortran/intrinsic-procedures/cos.rst | 91 + .../doc/gfortran/intrinsic-procedures/cosd.rst | 91 + .../doc/gfortran/intrinsic-procedures/cosh.rst | 73 + .../doc/gfortran/intrinsic-procedures/cosum.rst | 67 + .../doc/gfortran/intrinsic-procedures/cotan.rst | 71 + .../doc/gfortran/intrinsic-procedures/cotand.rst | 74 + .../doc/gfortran/intrinsic-procedures/count.rst | 72 + .../doc/gfortran/intrinsic-procedures/cputime.rst | 49 + .../doc/gfortran/intrinsic-procedures/cshift.rst | 61 + .../doc/gfortran/intrinsic-procedures/csizeof.rst | 55 + .../doc/gfortran/intrinsic-procedures/ctime.rst | 62 + .../gfortran/intrinsic-procedures/dateandtime.rst | 70 + .../doc/gfortran/intrinsic-procedures/dble.rst | 46 + .../doc/gfortran/intrinsic-procedures/dcmplx.rst | 54 + .../doc/gfortran/intrinsic-procedures/digits.rst | 46 + .../doc/gfortran/intrinsic-procedures/dim.rst | 78 + .../gfortran/intrinsic-procedures/dotproduct.rst | 57 + .../doc/gfortran/intrinsic-procedures/dprod.rst | 62 + .../doc/gfortran/intrinsic-procedures/dreal.rst | 43 + .../doc/gfortran/intrinsic-procedures/dshiftl.rst | 52 + .../doc/gfortran/intrinsic-procedures/dshiftr.rst | 52 + .../doc/gfortran/intrinsic-procedures/dtime.rst | 64 + .../doc/gfortran/intrinsic-procedures/eoshift.rst | 67 + .../doc/gfortran/intrinsic-procedures/epsilon.rst | 43 + .../doc/gfortran/intrinsic-procedures/erf.rst | 57 + .../doc/gfortran/intrinsic-procedures/erfc.rst | 57 + .../gfortran/intrinsic-procedures/erfcscaled.rst | 41 + .../doc/gfortran/intrinsic-procedures/etime.rst | 62 + .../gfortran/intrinsic-procedures/eventquery.rst | 57 + .../intrinsic-procedures/executecommandline.rst | 70 + .../doc/gfortran/intrinsic-procedures/exit.rst | 47 + .../doc/gfortran/intrinsic-procedures/exp.rst | 83 + .../doc/gfortran/intrinsic-procedures/exponent.rst | 44 + .../intrinsic-procedures/extendstypeof.rst | 41 + .../doc/gfortran/intrinsic-procedures/fdate.rst | 57 + .../doc/gfortran/intrinsic-procedures/fget.rst | 60 + .../doc/gfortran/intrinsic-procedures/fgetc.rst | 62 + .../doc/gfortran/intrinsic-procedures/findloc.rst | 78 + .../doc/gfortran/intrinsic-procedures/floor.rst | 51 + .../doc/gfortran/intrinsic-procedures/flush.rst | 72 + .../doc/gfortran/intrinsic-procedures/fnum.rst | 44 + .../doc/gfortran/intrinsic-procedures/fput.rst | 54 + .../doc/gfortran/intrinsic-procedures/fputc.rst | 60 + .../doc/gfortran/intrinsic-procedures/fraction.rst | 44 + .../doc/gfortran/intrinsic-procedures/free.rst | 43 + .../doc/gfortran/intrinsic-procedures/fseek.rst | 72 + .../doc/gfortran/intrinsic-procedures/fstat.rst | 47 + .../doc/gfortran/intrinsic-procedures/ftell.rst | 50 + .../doc/gfortran/intrinsic-procedures/gamma.rst | 67 + .../doc/gfortran/intrinsic-procedures/gerror.rst | 43 + .../doc/gfortran/intrinsic-procedures/getarg.rst | 64 + .../gfortran/intrinsic-procedures/getcommand.rst | 58 + .../intrinsic-procedures/getcommandargument.rst | 76 + .../doc/gfortran/intrinsic-procedures/getcwd.rst | 46 + .../doc/gfortran/intrinsic-procedures/getenv.rst | 49 + .../getenvironmentvariable.rst | 68 + .../doc/gfortran/intrinsic-procedures/getgid.rst | 37 + .../doc/gfortran/intrinsic-procedures/getlog.rst | 47 + .../doc/gfortran/intrinsic-procedures/getpid.rst | 43 + .../doc/gfortran/intrinsic-procedures/getuid.rst | 37 + .../doc/gfortran/intrinsic-procedures/gmtime.rst | 47 + .../doc/gfortran/intrinsic-procedures/hostnm.rst | 38 + .../doc/gfortran/intrinsic-procedures/huge.rst | 41 + .../doc/gfortran/intrinsic-procedures/hypot.rst | 45 + .../doc/gfortran/intrinsic-procedures/iachar.rst | 55 + .../doc/gfortran/intrinsic-procedures/iall.rst | 61 + .../doc/gfortran/intrinsic-procedures/iand.rst | 99 + .../doc/gfortran/intrinsic-procedures/iany.rst | 61 + .../doc/gfortran/intrinsic-procedures/iargc.rst | 44 + .../doc/gfortran/intrinsic-procedures/ibclr.rst | 87 + .../doc/gfortran/intrinsic-procedures/ibits.rst | 93 + .../doc/gfortran/intrinsic-procedures/ibset.rst | 85 + .../doc/gfortran/intrinsic-procedures/ichar.rst | 93 + .../doc/gfortran/intrinsic-procedures/idate.rst | 50 + .../doc/gfortran/intrinsic-procedures/ieor.rst | 91 + .../doc/gfortran/intrinsic-procedures/ierrno.rst | 37 + .../gfortran/intrinsic-procedures/imageindex.rst | 48 + .../doc/gfortran/intrinsic-procedures/index.rst | 72 + .../doc/gfortran/intrinsic-procedures/int.rst | 76 + .../doc/gfortran/intrinsic-procedures/int2.rst | 39 + .../doc/gfortran/intrinsic-procedures/int8.rst | 39 + .../introduction-to-intrinsic-procedures.rst | 43 + .../doc/gfortran/intrinsic-procedures/ior.rst | 91 + .../doc/gfortran/intrinsic-procedures/iparity.rst | 62 + .../doc/gfortran/intrinsic-procedures/irand.rst | 48 + .../doc/gfortran/intrinsic-procedures/isatty.rst | 46 + .../gfortran/intrinsic-procedures/iscontiguous.rst | 52 + .../doc/gfortran/intrinsic-procedures/ishft.rst | 85 + .../doc/gfortran/intrinsic-procedures/ishftc.rst | 91 + .../gfortran/intrinsic-procedures/isiostatend.rst | 48 + .../gfortran/intrinsic-procedures/isiostateor.rst | 48 + .../doc/gfortran/intrinsic-procedures/isnan.rst | 45 + .../doc/gfortran/intrinsic-procedures/itime.rst | 50 + .../doc/gfortran/intrinsic-procedures/kill.rst | 51 + .../doc/gfortran/intrinsic-procedures/kind.rst | 46 + .../doc/gfortran/intrinsic-procedures/lbound.rst | 51 + .../doc/gfortran/intrinsic-procedures/lcobound.rst | 48 + .../doc/gfortran/intrinsic-procedures/leadz.rst | 47 + .../doc/gfortran/intrinsic-procedures/len.rst | 62 + .../doc/gfortran/intrinsic-procedures/lentrim.rst | 43 + .../doc/gfortran/intrinsic-procedures/lge.rst | 63 + .../doc/gfortran/intrinsic-procedures/lgt.rst | 63 + .../doc/gfortran/intrinsic-procedures/link.rst | 45 + .../doc/gfortran/intrinsic-procedures/lle.rst | 63 + .../doc/gfortran/intrinsic-procedures/llt.rst | 63 + .../doc/gfortran/intrinsic-procedures/lnblnk.rst | 39 + .../doc/gfortran/intrinsic-procedures/loc.rst | 44 + .../doc/gfortran/intrinsic-procedures/log.rst | 93 + .../doc/gfortran/intrinsic-procedures/log10.rst | 69 + .../doc/gfortran/intrinsic-procedures/loggamma.rst | 76 + .../doc/gfortran/intrinsic-procedures/logical.rst | 43 + .../doc/gfortran/intrinsic-procedures/lshift.rst | 48 + .../doc/gfortran/intrinsic-procedures/lstat.rst | 49 + .../doc/gfortran/intrinsic-procedures/ltime.rst | 46 + .../doc/gfortran/intrinsic-procedures/malloc.rst | 66 + .../doc/gfortran/intrinsic-procedures/maskl.rst | 42 + .../doc/gfortran/intrinsic-procedures/maskr.rst | 42 + .../doc/gfortran/intrinsic-procedures/matmul.rst | 44 + .../doc/gfortran/intrinsic-procedures/max.rst | 86 + .../gfortran/intrinsic-procedures/maxexponent.rst | 45 + .../doc/gfortran/intrinsic-procedures/maxloc.rst | 76 + .../doc/gfortran/intrinsic-procedures/maxval.rst | 58 + .../doc/gfortran/intrinsic-procedures/mclock.rst | 39 + .../doc/gfortran/intrinsic-procedures/mclock8.rst | 39 + .../doc/gfortran/intrinsic-procedures/merge.rst | 41 + .../gfortran/intrinsic-procedures/mergebits.rst | 44 + .../doc/gfortran/intrinsic-procedures/min.rst | 86 + .../gfortran/intrinsic-procedures/minexponent.rst | 37 + .../doc/gfortran/intrinsic-procedures/minloc.rst | 76 + .../doc/gfortran/intrinsic-procedures/minval.rst | 58 + .../doc/gfortran/intrinsic-procedures/mod.rst | 118 + .../doc/gfortran/intrinsic-procedures/modulo.rst | 55 + .../gfortran/intrinsic-procedures/movealloc.rst | 51 + .../doc/gfortran/intrinsic-procedures/mvbits.rst | 95 + .../doc/gfortran/intrinsic-procedures/nearest.rst | 51 + .../doc/gfortran/intrinsic-procedures/newline.rst | 42 + .../doc/gfortran/intrinsic-procedures/nint.rst | 75 + .../doc/gfortran/intrinsic-procedures/norm2.rst | 46 + .../doc/gfortran/intrinsic-procedures/not.rst | 85 + .../doc/gfortran/intrinsic-procedures/null.rst | 41 + .../gfortran/intrinsic-procedures/numimages.rst | 61 + .../doc/gfortran/intrinsic-procedures/or.rst | 60 + .../doc/gfortran/intrinsic-procedures/pack.rst | 72 + .../doc/gfortran/intrinsic-procedures/parity.rst | 46 + .../doc/gfortran/intrinsic-procedures/perror.rst | 35 + .../doc/gfortran/intrinsic-procedures/popcnt.rst | 48 + .../doc/gfortran/intrinsic-procedures/poppar.rst | 50 + .../gfortran/intrinsic-procedures/precision.rst | 50 + .../doc/gfortran/intrinsic-procedures/present.rst | 47 + .../doc/gfortran/intrinsic-procedures/product.rst | 56 + .../doc/gfortran/intrinsic-procedures/radix.rst | 44 + .../doc/gfortran/intrinsic-procedures/ran.rst | 27 + .../doc/gfortran/intrinsic-procedures/rand.rst | 51 + .../gfortran/intrinsic-procedures/randominit.rst | 62 + .../gfortran/intrinsic-procedures/randomnumber.rst | 42 + .../gfortran/intrinsic-procedures/randomseed.rst | 62 + .../doc/gfortran/intrinsic-procedures/range.rst | 42 + .../doc/gfortran/intrinsic-procedures/rank.rst | 43 + .../doc/gfortran/intrinsic-procedures/real.rst | 104 + .../doc/gfortran/intrinsic-procedures/rename.rst | 44 + .../doc/gfortran/intrinsic-procedures/repeat.rst | 43 + .../doc/gfortran/intrinsic-procedures/reshape.rst | 62 + .../gfortran/intrinsic-procedures/rrspacing.rst | 38 + .../doc/gfortran/intrinsic-procedures/rshift.rst | 50 + .../gfortran/intrinsic-procedures/sametypeas.rst | 41 + .../doc/gfortran/intrinsic-procedures/scale.rst | 45 + .../doc/gfortran/intrinsic-procedures/scan.rst | 57 + .../doc/gfortran/intrinsic-procedures/secnds.rst | 52 + .../doc/gfortran/intrinsic-procedures/second.rst | 40 + .../intrinsic-procedures/selectedcharkind.rst | 56 + .../intrinsic-procedures/selectedintkind.rst | 48 + .../intrinsic-procedures/selectedrealkind.rst | 67 + .../gfortran/intrinsic-procedures/setexponent.rst | 48 + .../doc/gfortran/intrinsic-procedures/shape.rst | 55 + .../doc/gfortran/intrinsic-procedures/shifta.rst | 46 + .../doc/gfortran/intrinsic-procedures/shiftl.rst | 44 + .../doc/gfortran/intrinsic-procedures/shiftr.rst | 44 + .../doc/gfortran/intrinsic-procedures/sign.rst | 78 + .../doc/gfortran/intrinsic-procedures/signal.rst | 59 + .../doc/gfortran/intrinsic-procedures/sin.rst | 89 + .../doc/gfortran/intrinsic-procedures/sind.rst | 89 + .../doc/gfortran/intrinsic-procedures/sinh.rst | 66 + .../doc/gfortran/intrinsic-procedures/size.rst | 55 + .../doc/gfortran/intrinsic-procedures/sizeof.rst | 58 + .../doc/gfortran/intrinsic-procedures/sleep.rst | 36 + .../doc/gfortran/intrinsic-procedures/spacing.rst | 47 + .../doc/gfortran/intrinsic-procedures/spread.rst | 54 + .../doc/gfortran/intrinsic-procedures/sqrt.rst | 86 + .../doc/gfortran/intrinsic-procedures/srand.rst | 53 + .../doc/gfortran/intrinsic-procedures/stat.rst | 72 + .../gfortran/intrinsic-procedures/storagesize.rst | 42 + .../doc/gfortran/intrinsic-procedures/sum.rst | 56 + .../doc/gfortran/intrinsic-procedures/symlnk.rst | 46 + .../doc/gfortran/intrinsic-procedures/system.rst | 41 + .../gfortran/intrinsic-procedures/systemclock.rst | 57 + .../doc/gfortran/intrinsic-procedures/tan.rst | 70 + .../doc/gfortran/intrinsic-procedures/tand.rst | 70 + .../doc/gfortran/intrinsic-procedures/tanh.rst | 72 + .../gfortran/intrinsic-procedures/thisimage.rst | 75 + .../doc/gfortran/intrinsic-procedures/time.rst | 39 + .../doc/gfortran/intrinsic-procedures/time8.rst | 39 + .../doc/gfortran/intrinsic-procedures/tiny.rst | 36 + .../doc/gfortran/intrinsic-procedures/trailz.rst | 46 + .../doc/gfortran/intrinsic-procedures/transfer.rst | 55 + .../gfortran/intrinsic-procedures/transpose.rst | 34 + .../doc/gfortran/intrinsic-procedures/trim.rst | 45 + .../doc/gfortran/intrinsic-procedures/ttynam.rst | 47 + .../doc/gfortran/intrinsic-procedures/ubound.rst | 52 + .../doc/gfortran/intrinsic-procedures/ucobound.rst | 48 + .../doc/gfortran/intrinsic-procedures/umask.rst | 36 + .../doc/gfortran/intrinsic-procedures/unlink.rst | 41 + .../doc/gfortran/intrinsic-procedures/unpack.rst | 57 + .../doc/gfortran/intrinsic-procedures/verify.rst | 59 + .../doc/gfortran/intrinsic-procedures/xor.rst | 60 + gcc/fortran/doc/gfortran/introduction.rst | 18 + .../doc/gfortran/mixed-language-programming.rst | 37 + .../naming-and-argument-passing-conventions.rst | 178 + .../doc/gfortran/non-fortran-main-program.rst | 251 + gcc/fortran/doc/gfortran/projects.rst | 29 + gcc/fortran/doc/gfortran/runtime.rst | 33 + .../doc/gfortran/runtime/gfortranconvertunit.rst | 97 + .../gfortran/runtime/gfortranerrorbacktrace.rst | 16 + .../runtime/gfortranformattedbuffersize.rst | 13 + .../doc/gfortran/runtime/gfortranlistseparator.rst | 21 + .../doc/gfortran/runtime/gfortranoptionalplus.rst | 15 + .../doc/gfortran/runtime/gfortranshowlocus.rst | 14 + .../doc/gfortran/runtime/gfortranstderrunit.rst | 13 + .../doc/gfortran/runtime/gfortranstdinunit.rst | 13 + .../doc/gfortran/runtime/gfortranstdoutunit.rst | 13 + .../doc/gfortran/runtime/gfortranunbufferedall.rst | 15 + .../runtime/gfortranunbufferedpreconnected.rst | 15 + .../runtime/gfortranunformattedbuffersize.rst | 13 + gcc/fortran/doc/gfortran/runtime/tmpdir.rst | 22 + gcc/fortran/doc/gfortran/standards.rst | 130 + .../gfortran/type-and-enum-abi-documentation.rst | 189 + gcc/go/doc/c-interoperability.rst | 23 + gcc/go/doc/c-type-interoperability.rst | 77 + gcc/go/doc/compiler-directives.rst | 47 + gcc/go/doc/conf.py | 30 + gcc/go/doc/copyright.rst | 24 + gcc/go/doc/function-names.rst | 61 + gcc/go/doc/general-public-license-3.rst | 6 + gcc/go/doc/gnu-free-documentation-license.rst | 6 + gcc/go/doc/import-and-export.rst | 50 + gcc/go/doc/index.rst | 23 + gcc/go/doc/indices-and-tables.rst | 1 + gcc/go/doc/introduction.rst | 8 + gcc/go/doc/invoking-gccgo.rst | 214 + libgomp/doc/amd-radeon-gcn.rst | 57 + libgomp/doc/conf.py | 24 + libgomp/doc/copyright.rst | 25 + libgomp/doc/cuda-streams-usage.rst | 50 + libgomp/doc/enabling-openacc.rst | 24 + libgomp/doc/enabling-openmp.rst | 22 + .../first-invocation-nvidia-cublas-library-api.rst | 52 + .../doc/first-invocation-openacc-library-api.rst | 74 + libgomp/doc/funding.rst | 6 + libgomp/doc/general-public-license-3.rst | 6 + libgomp/doc/gnu-free-documentation-license.rst | 6 + ...-status-and-implementation-defined-behavior.rst | 281 ++ libgomp/doc/index.rst | 35 + libgomp/doc/indices-and-tables.rst | 1 + libgomp/doc/introduction.rst | 25 + libgomp/doc/memory-allocation-with-libmemkind.rst | 23 + libgomp/doc/nvptx.rst | 60 + libgomp/doc/offload-target-specifics.rst | 17 + libgomp/doc/openacc-environment-variables.rst | 23 + .../openacc-environment-variables/accdevicenum.rst | 13 + .../accdevicetype.rst | 13 + .../openacc-environment-variables/accproflib.rst | 16 + .../openacc-environment-variables/gccaccnotify.rst | 12 + libgomp/doc/openacc-introduction.rst | 21 + .../openacc-library-and-environment-variables.rst | 30 + libgomp/doc/openacc-library-interoperability.rst | 17 + libgomp/doc/openacc-profiling-interface.rst | 14 + libgomp/doc/openacc-runtime-library-routines.rst | 74 + .../accasynctest.rst | 36 + .../accasynctestall.rst | 34 + .../openacc-runtime-library-routines/accattach.rst | 25 + .../openacc-runtime-library-routines/acccopyin.rst | 58 + .../acccopyout.rst | 85 + .../openacc-runtime-library-routines/acccreate.rst | 58 + .../openacc-runtime-library-routines/accdelete.rst | 85 + .../openacc-runtime-library-routines/accdetach.rst | 29 + .../accdeviceptr.rst | 23 + .../openacc-runtime-library-routines/accfree.rst | 22 + .../accgetcudastream.rst | 23 + .../accgetcurrentcudacontext.rst | 23 + .../accgetcurrentcudadevice.rst | 23 + .../accgetdevicenum.rst | 34 + .../accgetdevicetype.rst | 36 + .../accgetnumdevices.rst | 31 + .../accgetproperty.rst | 60 + .../acchostptr.rst | 23 + .../openacc-runtime-library-routines/accinit.rst | 31 + .../accispresent.rst | 50 + .../openacc-runtime-library-routines/accmalloc.rst | 23 + .../accmapdata.rst | 24 + .../accmemcpyfromdevice.rst | 24 + .../accmemcpytodevice.rst | 24 + .../accondevice.rst | 37 + .../accpresentorcopyin.rst | 58 + .../accpresentorcreate.rst | 58 + .../accproflookup.rst | 25 + .../accprofregister.rst | 25 + .../accprofunregister.rst | 25 + .../accregisterlibrary.rst | 25 + .../accsetcudastream.rst | 28 + .../accsetdevicenum.rst | 34 + .../accsetdevicetype.rst | 31 + .../accshutdown.rst | 31 + .../accunmapdata.rst | 23 + .../accupdatedevice.rst | 58 + .../accupdateself.rst | 58 + .../openacc-runtime-library-routines/accwait.rst | 37 + .../accwaitall.rst | 32 + .../accwaitallasync.rst | 32 + .../accwaitasync.rst | 31 + libgomp/doc/openmp-context-selectors.rst | 28 + libgomp/doc/openmp-environment-variables.rst | 39 + .../gompcpuaffinity.rst | 37 + .../doc/openmp-environment-variables/gompdebug.rst | 18 + .../gomprtemsthreadpools.rst | 46 + .../openmp-environment-variables/gompspincount.rst | 30 + .../openmp-environment-variables/gompstacksize.rst | 25 + .../ompcancellation.rst | 21 + .../ompdefaultdevice.rst | 24 + .../openmp-environment-variables/ompdisplayenv.rst | 21 + .../openmp-environment-variables/ompdynamic.rst | 23 + .../ompmaxactivelevels.rst | 26 + .../ompmaxtaskpriority.rst | 25 + .../doc/openmp-environment-variables/ompnested.rst | 28 + .../openmp-environment-variables/ompnumteams.rst | 23 + .../openmp-environment-variables/ompnumthreads.rst | 24 + .../doc/openmp-environment-variables/ompplaces.rst | 54 + .../openmp-environment-variables/ompprocbind.rst | 34 + .../openmp-environment-variables/ompschedule.rst | 24 + .../openmp-environment-variables/ompstacksize.rst | 24 + .../omptargetoffload.rst | 27 + .../ompteamsthreadlimit.rst | 24 + .../ompthreadlimit.rst | 22 + .../openmp-environment-variables/ompwaitpolicy.rst | 24 + libgomp/doc/openmp-implementation-specifics.rst | 15 + libgomp/doc/openmp-implementation-status.rst | 21 + .../doc/openmp-implementation-status/openmp-45.rst | 11 + .../doc/openmp-implementation-status/openmp-50.rst | 212 + .../doc/openmp-implementation-status/openmp-51.rst | 177 + .../doc/openmp-implementation-status/openmp-52.rst | 132 + libgomp/doc/openmp-runtime-library-routines.rst | 87 + .../ompdestroylock.rst | 33 + .../ompdestroynestlock.rst | 33 + .../ompfulfillevent.rst | 36 + .../ompgetactivelevel.rst | 31 + .../ompgetancestorthreadnum.rst | 35 + .../ompgetcancellation.rst | 33 + .../ompgetdefaultdevice.rst | 30 + .../ompgetdevicenum.rst | 33 + .../ompgetdynamic.rst | 37 + .../ompgetinitialdevice.rst | 32 + .../ompgetlevel.rst | 31 + .../ompgetmaxactivelevels.rst | 30 + .../ompgetmaxtaskpriority.rst | 29 + .../ompgetmaxteams.rst | 31 + .../ompgetmaxthreads.rst | 31 + .../ompgetnested.rst | 48 + .../ompgetnumdevices.rst | 27 + .../ompgetnumprocs.rst | 27 + .../ompgetnumteams.rst | 27 + .../ompgetnumthreads.rst | 38 + .../ompgetprocbind.rst | 34 + .../ompgetschedule.rst | 37 + .../ompgetsupportedactivelevels.rst | 31 + .../ompgetteamnum.rst | 27 + .../ompgetteamsize.rst | 36 + .../ompgetteamsthreadlimit.rst | 31 + .../ompgetthreadlimit.rst | 30 + .../ompgetthreadnum.rst | 34 + .../ompgetwtick.rst | 31 + .../ompgetwtime.rst | 33 + .../openmp-runtime-library-routines/ompinfinal.rst | 29 + .../ompinitlock.rst | 33 + .../ompinitnestlock.rst | 33 + .../ompinparallel.rst | 29 + .../ompisinitialdevice.rst | 29 + .../ompsetdefaultdevice.rst | 33 + .../ompsetdynamic.rst | 35 + .../openmp-runtime-library-routines/ompsetlock.rst | 35 + .../ompsetmaxactivelevels.rst | 35 + .../ompsetnested.rst | 40 + .../ompsetnestlock.rst | 35 + .../ompsetnumteams.rst | 34 + .../ompsetnumthreads.rst | 34 + .../ompsetschedule.rst | 40 + .../ompsetteamsthreadlimit.rst | 35 + .../omptestlock.rst | 36 + .../omptestnestlock.rst | 36 + .../ompunsetlock.rst | 36 + .../ompunsetnestlock.rst | 36 + libgomp/doc/reporting-bugs.rst | 14 + libgomp/doc/the-libgomp-abi.rst | 31 + .../implementing-atomic-construct.rst | 21 + .../implementing-barrier-construct.rst | 13 + .../implementing-critical-construct.rst | 30 + ...-lastprivate-copyin-and-copyprivate-clauses.rst | 45 + .../implementing-flush-construct.rst | 11 + .../the-libgomp-abi/implementing-for-construct.rst | 73 + .../implementing-master-construct.rst | 18 + .../implementing-openaccs-parallel-construct.rst | 13 + .../implementing-ordered-construct.rst | 14 + .../implementing-parallel-construct.rst | 55 + .../implementing-private-clause.rst | 17 + .../implementing-reduction-clause.rst | 15 + .../implementing-sections-construct.rst | 42 + .../implementing-single-construct.rst | 48 + .../implementing-threadprivate-construct.rst | 18 + libiberty/doc/bsd.rst | 6 + libiberty/doc/conf.py | 25 + libiberty/doc/copyright.rst | 13 + libiberty/doc/extensions.rst | 767 +++ .../doc/function-variable-and-macro-listing.rst | 1857 ++++++++ libiberty/doc/index.rst | 23 + libiberty/doc/indices-and-tables.rst | 1 + libiberty/doc/introduction.rst | 8 + .../doc/lesser-general-public-license-2.1.rst | 6 + libiberty/doc/overview.rst | 20 + libiberty/doc/replacement-functions.rst | 62 + libiberty/doc/supplemental-functions.rst | 31 + libiberty/doc/using.rst | 40 + libitm/doc/c-c++-language-constructs-for-tm.rst | 39 + libitm/doc/conf.py | 24 + libitm/doc/copyright.rst | 13 + libitm/doc/enabling-libitm.rst | 13 + libitm/doc/gnu-free-documentation-license.rst | 6 + libitm/doc/index.rst | 27 + libitm/doc/indices-and-tables.rst | 1 + libitm/doc/internals.rst | 16 + libitm/doc/locking-conventions.rst | 261 ++ libitm/doc/nesting-flat-vs-closed.rst | 28 + libitm/doc/the-libitm-abi.rst | 27 + libitm/doc/the-libitm-abi/function-list.rst | 272 ++ .../future-enhancements-to-the-abi.rst | 7 + .../the-libitm-abi/library-design-principles.rst | 61 + libitm/doc/the-libitm-abi/memory-model.rst | 18 + libitm/doc/the-libitm-abi/non-objectives.rst | 7 + libitm/doc/the-libitm-abi/objectives.rst | 7 + libitm/doc/the-libitm-abi/sample-code.rst | 10 + .../doc/the-libitm-abi/types-and-macros-list.rst | 10 + libitm/doc/tm-methods-and-method-groups.rst | 47 + libquadmath/doc/conf.py | 24 + libquadmath/doc/copyright.rst | 18 + libquadmath/doc/gnu-free-documentation-license.rst | 6 + libquadmath/doc/i-o-library-routines.rst | 15 + libquadmath/doc/index.rst | 23 + libquadmath/doc/indices-and-tables.rst | 1 + libquadmath/doc/introduction.rst | 7 + libquadmath/doc/math-library-routines.rst | 104 + libquadmath/doc/quadmathsnprintf.rst | 74 + libquadmath/doc/reporting-bugs.rst | 12 + libquadmath/doc/strtoflt128.rst | 40 + libquadmath/doc/typedef-and-constants.rst | 43 + 1335 files changed, 176984 insertions(+) diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000000..9e305a8e7da --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,97 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS ?= -j auto -q +SPHINXBUILD ?= sphinx-build +PAPER ?= +SOURCEDIR = . +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_elements.papersize=a4paper +PAPEROPT_letter = -D latex_elements.papersize=letterpaper +# $(O) is meant as a shortcut for $(SPHINXOPTS) +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(O) $(SOURCEDIR) +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(O) $(SOURCEDIR) + +.PHONY: help +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and an HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files (you can set PAPER=a4 or PAPER=letter)" + @echo " latexpdf to make LaTeX files and then PDFs out of them" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " lualatexpdf to make LaTeX files and run them through lualatex" + @echo " xelatexpdf to make LaTeX files and run them through xelatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + @echo " dummy to check syntax errors of document sources" + +.PHONY: clean +clean: + rm -rf $(BUILDDIR) + +.PHONY: latexpdf +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) LATEXMKOPTS="-interaction=nonstopmode -f" -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: latexpdfja +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: lualatexpdf +lualatexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through lualatex..." + $(MAKE) PDFLATEX=lualatex -C $(BUILDDIR)/latex all-pdf + @echo "lualatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: xelatexpdf +xelatexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through xelatex..." + $(MAKE) PDFLATEX=xelatex -C $(BUILDDIR)/latex all-pdf + @echo "xelatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: info +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +.PHONY: gettext +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + +# Catch-all target: route all unknown targets to Sphinx +.PHONY: Makefile +%: Makefile + $(SPHINXBUILD) -b "$@" $(ALLSPHINXOPTS) "$(BUILDDIR)/$@" + diff --git a/doc/_static/custom.css b/doc/_static/custom.css new file mode 100644 index 00000000000..1282a993e2a --- /dev/null +++ b/doc/_static/custom.css @@ -0,0 +1,11 @@ +.sidebar-brand-text { + font-size: 13pt; +} + +.literal { + white-space: nowrap !important; +} + +.wy-nav-content { + max-width: initial; +} diff --git a/doc/baseconf.py b/doc/baseconf.py new file mode 100644 index 00000000000..2eea8298dae --- /dev/null +++ b/doc/baseconf.py @@ -0,0 +1,230 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import subprocess +import sys +# sys.path.insert(0, os.path.abspath('.')) + +# gccint needs a deeper stack limit +sys.setrecursionlimit(2000) + +# -- Project information ----------------------------------------------------- + +# The full version, including alpha/beta/rc tags + +# FIXME +folder = os.path.dirname(os.path.realpath(__file__)) +gcc_srcdir = os.path.join(folder, './objdir') + + +def __read_file(name): + path = os.path.join(gcc_srcdir, name) + if os.path.exists(path): + return open(path).read().strip() + else: + return '' + + +def __get_git_revision(): + try: + r = subprocess.check_output('git rev-parse --short HEAD', shell=True, encoding='utf8', + stderr=subprocess.DEVNULL) + return r.strip() + except subprocess.CalledProcessError: + return None + + +def __get_builder_name(): + if '-b' in sys.argv: + return sys.argv[sys.argv.index('-b') + 1] + else: + return None + + +gcc_BASEVER = __read_file('BASE-VER') +gcc_DEVPHASE = __read_file('DEV-PHASE') +gcc_DATESTAMP = __read_file('DATESTAMP') +gcc_REVISION = __read_file('REVISION') + +VERSION_PACKAGE = os.getenv('VERSION_PACKAGE', '(GCC)') +BUGURL = os.getenv('BUGURL', 'https://gcc.gnu.org/bugs/') +MONOCHROMATIC = os.getenv('MONOCHROMATIC') + +# The short X.Y version. +version = gcc_BASEVER + +# The full version, including alpha/beta/rc tags. +release = ('%s (%s %s%s)' + % (gcc_BASEVER, gcc_DEVPHASE, gcc_DATESTAMP, + (' %s' % gcc_REVISION) if gcc_REVISION else '')) + +rst_prolog = r''' +.. |gol| raw:: latex + + \\ +.. |nbsp| unicode:: 0xA0 + :trim: +''' + +needs_sphinx = '5.3' + +rst_epilog = ''' +.. |gcc_version| replace:: %s +.. |package_version| replace:: %s +.. |bugurl| replace:: %s +.. |needs_sphinx| replace:: %s +''' % (gcc_BASEVER, VERSION_PACKAGE, BUGURL, needs_sphinx) + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'gcc_sphinx', + 'sphinx.ext.intersphinx', + 'sphinx.ext.extlinks', + 'sphinx.ext.todo', +] + +if __get_builder_name() == 'html': + extensions.append('sphinx_copybutton') + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build'] + +# Do not highlight by default +highlight_language = 'none' + +# Select C++ as a primary domain +primary_domain = 'cpp' + +cpp_id_attributes = ['HOST_WIDE_INT', '__memx'] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'furo' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +html_theme_options = { + 'navigation_with_keys': True, +} + +html_logo = '../logo.svg' + +html_favicon = '../favicon.ico' + +html_last_updated_fmt = '' + +html_context = { + 'commit': __get_git_revision() +} + +html_static_path = [ + '../_static' +] + +html_css_files = [ + 'custom.css' +] + +# By default, do not generate any manual pages +man_pages = [] + +# FIXME: handle WARNINGs: unknown option issues and cross refs +suppress_warnings = [ + 'ref.option', +] + +# Use xelatex by default +latex_engine = 'xelatex' + +latex_logo = '../logo.pdf' + +latex_elements = { + 'pointsize': '11pt', + 'fontpkg': r''' +\setmonofont[Scale=0.8]{DejaVu Sans Mono} +''', + 'preamble': r''' +\fvset{formatcom=\let\textbf\relax} +\protected\def\sphinxcrossref#1{#1} +''', +} + +if MONOCHROMATIC: + latex_elements['sphinxsetup'] = r''' +TitleColor={black}, +InnerLinkColor={rgb}{0.0, 0.2, 0.6}, +OuterLinkColor={rgb}{0.0, 0.2, 0.6}, +''' + +latex_table_style = ['colorrows'] + +texinfo_cross_references = False + +texinfo_elements = {'preamble': """ +@definfoenclose strong,*,* +@definfoenclose emph,',' +""" +} + +# Use default as RTD theme uses default as well +pygments_style = 'bw' if MONOCHROMATIC else 'default' + +option_emphasise_placeholders = True + +# Ignore GitHub domain for link checking: +# https://github.com/sphinx-doc/sphinx/issues/9016 +linkcheck_ignore = [ + 'https://github.com/.*#.*' +] + +USER_LEVEL_DOCS = ('install', 'gcc', 'gfortran', 'cpp', 'gnat_rm', 'gnat_ugn', + 'gccgo', 'libgomp', 'libquadmath', 'libgccjit') +INTERNAL_DOCS = ('gccint', 'cppinternals', 'gfc-internals', 'gnat-style') + +# Cross manual reference mapping +intersphinx_mapping = {} +for manual in USER_LEVEL_DOCS + INTERNAL_DOCS: + intersphinx_mapping[manual] = (f'https://splichal.eu/scripts/sphinx/{manual}/_build/html/', None) + +# Custom references +extlinks = { + 'P': ('https://wg21.link/p%s', 'P%s'), + 'PR': ('https://gcc.gnu.org/PR%s', 'PR%s'), + 'openmp': ('https://openmp.org/specifications/#%s', 'OpenMP specification v%s'), + 'openacc': ('https://openacc.org/specification#%s', 'OpenACC specification v%s'), +} + +extlinks_detect_hardcoded_links = True + +# Set common settings where we need NAME of the documentation +def set_common(name, module): + module['tags'].add(name) + if gcc_DEVPHASE == 'experimental': + module['todo_include_todos'] = True + module['tags'].add('development') + + html_theme_options['source_edit_link'] = f'https://splichal.eu/scripts/sphinx/{name}' \ + '/_build/html/_sources/{filename}.txt' diff --git a/doc/bsd.rst b/doc/bsd.rst new file mode 100644 index 00000000000..6d53fa6271c --- /dev/null +++ b/doc/bsd.rst @@ -0,0 +1,39 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +BSD +=== + +Copyright (C) 1990 Regents of the University of California. +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: + +#. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +#. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +#. [rescinded 22 July 1999] + +#. Neither the name of the University nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS 'AS IS' AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +SUCH DAMAGE. \ No newline at end of file diff --git a/doc/contrib.rst b/doc/contrib.rst new file mode 100644 index 00000000000..273d61717b1 --- /dev/null +++ b/doc/contrib.rst @@ -0,0 +1,1273 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: contributors + +.. _contributors: + +Contributors to GCC +=================== + +The GCC project would like to thank its many contributors. Without them the +project would not have been nearly as successful as it has been. Any omissions +in this list are accidental. Feel free to contact +law@redhat.com or gerald@pfeifer.com if you have been left +out or some of your contributions are not listed. Please keep this list in +alphabetical order. + +* Analog Devices helped implement the support for complex data types + and iterators. + +* John David Anglin for threading-related fixes and improvements to + libstdc++-v3, and the HP-UX port. + +* James van Artsdalen wrote the code that makes efficient use of + the Intel 80387 register stack. + +* Abramo and Roberto Bagnara for the SysV68 Motorola 3300 Delta Series + port. + +* Alasdair Baird for various bug fixes. + +* Giovanni Bajo for analyzing lots of complicated C++ problem reports. + +* Peter Barada for his work to improve code generation for new + ColdFire cores. + +* Gerald Baumgartner added the signature extension to the C++ front end. + +* Godmar Back for his Java improvements and encouragement. + +* Scott Bambrough for help porting the Java compiler. + +* Wolfgang Bangerth for processing tons of bug reports. + +* Jon Beniston for his Microsoft Windows port of Java and port to Lattice Mico32. + +* Daniel Berlin for better DWARF 2 support, faster/better optimizations, + improved alias analysis, plus migrating GCC to Bugzilla. + +* Geoff Berry for his Java object serialization work and various patches. + +* David Binderman tests weekly snapshots of GCC trunk against Fedora Rawhide + for several architectures. + +* Laurynas Biveinis for memory management work and DJGPP port fixes. + +* Uros Bizjak for the implementation of x87 math built-in functions and + for various middle end and i386 back end improvements and bug fixes. + +* Eric Blake for helping to make GCJ and libgcj conform to the + specifications. + +* Janne Blomqvist for contributions to GNU Fortran. + +* Hans-J. Boehm for his garbage collector, IA-64 libffi port, and other + Java work. + +* Segher Boessenkool for helping maintain the PowerPC port and the + instruction combiner plus various contributions to the middle end. + +* Neil Booth for work on cpplib, lang hooks, debug hooks and other + miscellaneous clean-ups. + +* Steven Bosscher for integrating the GNU Fortran front end into GCC and for + contributing to the tree-ssa branch. + +* Eric Botcazou for fixing middle- and backend bugs left and right. + +* Per Bothner for his direction via the steering committee and various + improvements to the infrastructure for supporting new languages. Chill + front end implementation. Initial implementations of + cpplib, fix-header, config.guess, libio, and past C++ library (libg++) + maintainer. Dreaming up, designing and implementing much of GCJ. + +* Devon Bowen helped port GCC to the Tahoe. + +* Don Bowman for mips-vxworks contributions. + +* James Bowman for the FT32 port. + +* Dave Brolley for work on cpplib and Chill. + +* Paul Brook for work on the ARM architecture and maintaining GNU Fortran. + +* Robert Brown implemented the support for Encore 32000 systems. + +* Christian Bruel for improvements to local store elimination. + +* Herman A.J. ten Brugge for various fixes. + +* Joerg Brunsmann for Java compiler hacking and help with the GCJ FAQ. + +* Joe Buck for his direction via the steering committee from its creation + to 2013. + +* Iain Buclaw for the D frontend. + +* Craig Burley for leadership of the G77 Fortran effort. + +* Tobias Burnus for contributions to GNU Fortran. + +* Stephan Buys for contributing Doxygen notes for libstdc++. + +* Paolo Carlini for libstdc++ work: lots of efficiency improvements to + the C++ strings, streambufs and formatted I/O, hard detective work on + the frustrating localization issues, and keeping up with the problem reports. + +* John Carr for his alias work, SPARC hacking, infrastructure improvements, + previous contributions to the steering committee, loop optimizations, etc. + +* Stephane Carrez for 68HC11 and 68HC12 ports. + +* Steve Chamberlain for support for the Renesas SH and H8 processors + and the PicoJava processor, and for GCJ config fixes. + +* Glenn Chambers for help with the GCJ FAQ. + +* John-Marc Chandonia for various libgcj patches. + +* Denis Chertykov for contributing and maintaining the AVR port, the first GCC port + for an 8-bit architecture. + +* Kito Cheng for his work on the RISC-V port, including bringing up the test + suite and maintenance. + +* Scott Christley for his Objective-C contributions. + +* Eric Christopher for his Java porting help and clean-ups. + +* Branko Cibej for more warning contributions. + +* The `GNU Classpath project `_ + for all of their merged runtime code. + +* Nick Clifton for arm, mcore, fr30, v850, m32r, msp430 rx work, + :option:`--help`, and other random hacking. + +* Michael Cook for libstdc++ cleanup patches to reduce warnings. + +* R. Kelley Cook for making GCC buildable from a read-only directory as + well as other miscellaneous build process and documentation clean-ups. + +* Ralf Corsepius for SH testing and minor bug fixing. + +* François-Xavier Coudert for contributions to GNU Fortran. + +* Stan Cox for care and feeding of the x86 port and lots of behind + the scenes hacking. + +* Alex Crain provided changes for the 3b1. + +* Ian Dall for major improvements to the NS32k port. + +* Paul Dale for his work to add uClinux platform support to the + m68k backend. + +* Palmer Dabbelt for his work maintaining the RISC-V port. + +* Dario Dariol contributed the four varieties of sample programs + that print a copy of their source. + +* Russell Davidson for fstream and stringstream fixes in libstdc++. + +* Bud Davis for work on the G77 and GNU Fortran compilers. + +* Mo DeJong for GCJ and libgcj bug fixes. + +* Jerry DeLisle for contributions to GNU Fortran. + +* DJ Delorie for the DJGPP port, build and libiberty maintenance, + various bug fixes, and the M32C, MeP, MSP430, and RL78 ports. + +* Arnaud Desitter for helping to debug GNU Fortran. + +* Gabriel Dos Reis for contributions to G++, contributions and + maintenance of GCC diagnostics infrastructure, libstdc++-v3, + including ``valarray<>``, ``complex<>``, maintaining the numerics library + (including that pesky ```` :-) and keeping up-to-date anything + to do with numbers. + +* Ulrich Drepper for his work on glibc, testing of GCC using glibc, ISO C99 + support, CFG dumping support, etc., plus support of the C++ runtime + libraries including for all kinds of C interface issues, contributing and + maintaining ``complex<>``, sanity checking and disbursement, configuration + architecture, libio maintenance, and early math work. + +* François Dumont for his work on libstdc++-v3, especially maintaining and + improving ``debug-mode`` and associative and unordered containers. + +* Zdenek Dvorak for a new loop unroller and various fixes. + +* Michael Eager for his work on the Xilinx MicroBlaze port. + +* Richard Earnshaw for his ongoing work with the ARM. + +* David Edelsohn for his direction via the steering committee, ongoing work + with the RS6000/PowerPC port, help cleaning up Haifa loop changes, + doing the entire AIX port of libstdc++ with his bare hands, and for + ensuring GCC properly keeps working on AIX. + +* Kevin Ediger for the floating point formatting of num_put::do_put in + libstdc++. + +* Phil Edwards for libstdc++ work including configuration hackery, + documentation maintainer, chief breaker of the web pages, the occasional + iostream bug fix, and work on shared library symbol versioning. + +* Paul Eggert for random hacking all over GCC. + +* Mark Elbrecht for various DJGPP improvements, and for libstdc++ + configuration support for locales and fstream-related fixes. + +* Vadim Egorov for libstdc++ fixes in strings, streambufs, and iostreams. + +* Christian Ehrhardt for dealing with bug reports. + +* Ben Elliston for his work to move the Objective-C runtime into its + own subdirectory and for his work on autoconf. + +* Revital Eres for work on the PowerPC 750CL port. + +* Marc Espie for OpenBSD support. + +* Doug Evans for much of the global optimization framework, arc, m32r, + and SPARC work. + +* Christopher Faylor for his work on the Cygwin port and for caring and + feeding the gcc.gnu.org box and saving its users tons of spam. + +* Fred Fish for BeOS support and Ada fixes. + +* Ivan Fontes Garcia for the Portuguese translation of the GCJ FAQ. + +* Peter Gerwinski for various bug fixes and the Pascal front end. + +* Kaveh R. Ghazi for his direction via the steering committee, amazing + work to make :samp:`-W -Wall -W* -Werror` useful, and + testing GCC on a plethora of platforms. Kaveh extends his gratitude to + the CAIP Center at Rutgers University for providing him with computing + resources to work on Free Software from the late 1980s to 2010. + +* John Gilmore for a donation to the FSF earmarked improving GNU Java. + +* Judy Goldberg for c++ contributions. + +* Torbjorn Granlund for various fixes and the c-torture testsuite, + multiply- and divide-by-constant optimization, improved long long + support, improved leaf function register allocation, and his direction + via the steering committee. + +* Jonny Grant for improvements to ``collect2's`` :option:`--help` documentation. + +* Anthony Green for his :option:`-Os` contributions, the moxie port, and + Java front end work. + +* Stu Grossman for gdb hacking, allowing GCJ developers to debug Java code. + +* Michael K. Gschwind contributed the port to the PDP-11. + +* Richard Biener for his ongoing middle-end contributions and bug fixes + and for release management. + +* Ron Guilmette implemented the :command:`protoize` and :command:`unprotoize` + tools, the support for DWARF 1 symbolic debugging information, and much of + the support for System V Release 4. He has also worked heavily on the + Intel 386 and 860 support. + +* Sumanth Gundapaneni for contributing the CR16 port. + +* Mostafa Hagog for Swing Modulo Scheduling (SMS) and post reload GCSE. + +* Bruno Haible for improvements in the runtime overhead for EH, new + warnings and assorted bug fixes. + +* Andrew Haley for his amazing Java compiler and library efforts. + +* Chris Hanson assisted in making GCC work on HP-UX for the 9000 series 300. + +* Michael Hayes for various thankless work he's done trying to get + the c30/c40 ports functional. Lots of loop and unroll improvements and + fixes. + +* Dara Hazeghi for wading through myriads of target-specific bug reports. + +* Kate Hedstrom for staking the G77 folks with an initial testsuite. + +* Richard Henderson for his ongoing SPARC, alpha, ia32, and ia64 work, loop + opts, and generally fixing lots of old problems we've ignored for + years, flow rewrite and lots of further stuff, including reviewing + tons of patches. + +* Aldy Hernandez for working on the PowerPC port, SIMD support, and + various fixes. + +* Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed + the support for the Sony NEWS machine. + +* Kazu Hirata for caring and feeding the Renesas H8/300 port and various fixes. + +* Katherine Holcomb for work on GNU Fortran. + +* Manfred Hollstein for his ongoing work to keep the m88k alive, lots + of testing and bug fixing, particularly of GCC configury code. + +* Steve Holmgren for MachTen patches. + +* Mat Hostetter for work on the TILE-Gx and TILEPro ports. + +* Jan Hubicka for his x86 port improvements. + +* Falk Hueffner for working on C and optimization bug reports. + +* Bernardo Innocenti for his m68k work, including merging of + ColdFire improvements and uClinux support. + +* Christian Iseli for various bug fixes. + +* Kamil Iskra for general m68k hacking. + +* Lee Iverson for random fixes and MIPS testing. + +* Balaji V. Iyer for Cilk+ development and merging. + +* Andreas Jaeger for testing and benchmarking of GCC and various bug fixes. + +* Martin Jambor for his work on inter-procedural optimizations, the + switch conversion pass, and scalar replacement of aggregates. + +* Jakub Jelinek for his SPARC work and sibling call optimizations as well + as lots of bug fixes and test cases, and for improving the Java build + system. + +* Janis Johnson for ia64 testing and fixes, her quality improvement + sidetracks, and web page maintenance. + +* Kean Johnston for SCO OpenServer support and various fixes. + +* Tim Josling for the sample language treelang based originally on Richard + Kenner's 'toy' language. + +* Nicolai Josuttis for additional libstdc++ documentation. + +* Klaus Kaempf for his ongoing work to make alpha-vms a viable target. + +* Steven G. Kargl for work on GNU Fortran. + +* David Kashtan of SRI adapted GCC to VMS. + +* Ryszard Kabatek for many, many libstdc++ bug fixes and optimizations of + strings, especially member functions, and for auto_ptr fixes. + +* Geoffrey Keating for his ongoing work to make the PPC work for GNU/Linux + and his automatic regression tester. + +* Brendan Kehoe for his ongoing work with G++ and for a lot of early work + in just about every part of libstdc++. + +* Oliver M. Kellogg of Deutsche Aerospace contributed the port to the + MIL-STD-1750A. + +* Richard Kenner of the New York University Ultracomputer Research + Laboratory wrote the machine descriptions for the AMD 29000, the DEC + Alpha, the IBM RT PC, and the IBM RS/6000 as well as the support for + instruction attributes. He also made changes to better support RISC + processors including changes to common subexpression elimination, + strength reduction, function calling sequence handling, and condition + code support, in addition to generalizing the code for frame pointer + elimination and delay slot scheduling. Richard Kenner was also the + head maintainer of GCC for several years. + +* Mumit Khan for various contributions to the Cygwin and Mingw32 ports and + maintaining binary releases for Microsoft Windows hosts, and for massive libstdc++ + porting work to Cygwin/Mingw32. + +* Robin Kirkham for cpu32 support. + +* Mark Klein for PA improvements. + +* Thomas Koenig for various bug fixes. + +* Bruce Korb for the new and improved fixincludes code. + +* Benjamin Kosnik for his G++ work and for leading the libstdc++-v3 effort. + +* Maxim Kuvyrkov for contributions to the instruction scheduler, the Android + and m68k/Coldfire ports, and optimizations. + +* Charles LaBrec contributed the support for the Integrated Solutions + 68020 system. + +* Asher Langton and Mike Kumbera for contributing Cray pointer support + to GNU Fortran, and for other GNU Fortran improvements. + +* Jeff Law for his direction via the steering committee, coordinating the + entire egcs project and GCC 2.95, rolling out snapshots and releases, + handling merges from GCC2, reviewing tons of patches that might have + fallen through the cracks else, and random but extensive hacking. + +* Walter Lee for work on the TILE-Gx and TILEPro ports. + +* Marc Lehmann for his direction via the steering committee and helping + with analysis and improvements of x86 performance. + +* Victor Leikehman for work on GNU Fortran. + +* Ted Lemon wrote parts of the RTL reader and printer. + +* Kriang Lerdsuwanakij for C++ improvements including template as template + parameter support, and many C++ fixes. + +* Warren Levy for tremendous work on libgcj (Java Runtime Library) and + random work on the Java front end. + +* Alain Lichnewsky ported GCC to the MIPS CPU. + +* Oskar Liljeblad for hacking on AWT and his many Java bug reports and + patches. + +* Robert Lipe for OpenServer support, new testsuites, testing, etc. + +* Chen Liqin for various S+core related fixes/improvement, and for + maintaining the S+core port. + +* Martin Liska for his work on identical code folding, the sanitizers, + HSA, general bug fixing and for running automated regression testing of GCC + and reporting numerous bugs. + +* Weiwen Liu for testing and various bug fixes. + +* Manuel López-Ibáñez for improving :option:`-Wconversion` and + many other diagnostics fixes and improvements. + +* Dave Love for his ongoing work with the Fortran front end and + runtime libraries. + +* Martin von Löwis for internal consistency checking infrastructure, + various C++ improvements including namespace support, and tons of + assistance with libstdc++/compiler merges. + +* H.J. Lu for his previous contributions to the steering committee, many x86 + bug reports, prototype patches, and keeping the GNU/Linux ports working. + +* Greg McGary for random fixes and (someday) bounded pointers. + +* Andrew MacLeod for his ongoing work in building a real EH system, + various code generation improvements, work on the global optimizer, etc. + +* Vladimir Makarov for hacking some ugly i960 problems, PowerPC hacking + improvements to compile-time performance, overall knowledge and + direction in the area of instruction scheduling, design and + implementation of the automaton based instruction scheduler and + design and implementation of the integrated and local register allocators. + +* David Malcolm for his work on improving GCC diagnostics, JIT, self-tests + and unit testing. + +* Bob Manson for his behind the scenes work on dejagnu. + +* John Marino for contributing the DragonFly BSD port. + +* Philip Martin for lots of libstdc++ string and vector iterator fixes and + improvements, and string clean up and testsuites. + +* Michael Matz for his work on dominance tree discovery, the x86-64 port, + link-time optimization framework and general optimization improvements. + +* All of the Mauve project contributors for Java test code. + +* Bryce McKinlay for numerous GCJ and libgcj fixes and improvements. + +* Adam Megacz for his work on the Microsoft Windows port of GCJ. + +* Michael Meissner for LRS framework, ia32, m32r, v850, m88k, MIPS, + powerpc, haifa, ECOFF debug support, and other assorted hacking. + +* Jason Merrill for his direction via the steering committee and leading + the G++ effort. + +* Martin Michlmayr for testing GCC on several architectures using the + entire Debian archive. + +* David Miller for his direction via the steering committee, lots of + SPARC work, improvements in jump.cc and interfacing with the Linux kernel + developers. + +* Gary Miller ported GCC to Charles River Data Systems machines. + +* Alfred Minarik for libstdc++ string and ios bug fixes, and turning the + entire libstdc++ testsuite namespace-compatible. + +* Mark Mitchell for his direction via the steering committee, mountains of + C++ work, load/store hoisting out of loops, alias analysis improvements, + ISO C ``restrict`` support, and serving as release manager from 2000 + to 2011. + +* Alan Modra for various GNU/Linux bits and testing. + +* Toon Moene for his direction via the steering committee, Fortran + maintenance, and his ongoing work to make us make Fortran run fast. + +* Jason Molenda for major help in the care and feeding of all the services + on the gcc.gnu.org (formerly egcs.cygnus.com) machine---mail, web + services, ftp services, etc etc. Doing all this work on scrap paper and + the backs of envelopes would have been... difficult. + +* Catherine Moore for fixing various ugly problems we have sent her + way, including the haifa bug which was killing the Alpha & PowerPC + Linux kernels. + +* Mike Moreton for his various Java patches. + +* David Mosberger-Tang for various Alpha improvements, and for the initial + IA-64 port. + +* Stephen Moshier contributed the floating point emulator that assists in + cross-compilation and permits support for floating point numbers wider + than 64 bits and for ISO C99 support. + +* Bill Moyer for his behind the scenes work on various issues. + +* Philippe De Muyter for his work on the m68k port. + +* Joseph S. Myers for his work on the PDP-11 port, format checking and ISO + C99 support, and continuous emphasis on (and contributions to) documentation. + +* Nathan Myers for his work on libstdc++-v3: architecture and authorship + through the first three snapshots, including implementation of locale + infrastructure, string, shadow C headers, and the initial project + documentation (DESIGN, CHECKLIST, and so forth). Later, more work on + MT-safe string and shadow headers. + +* Felix Natter for documentation on porting libstdc++. + +* Nathanael Nerode for cleaning up the configuration/build process. + +* NeXT, Inc. donated the front end that supports the Objective-C + language. + +* Hans-Peter Nilsson for the CRIS and MMIX ports, improvements to the search + engine setup, various documentation fixes and other small fixes. + +* Geoff Noer for his work on getting cygwin native builds working. + +* Vegard Nossum for running automated regression testing of GCC and reporting + numerous bugs. + +* Diego Novillo for his work on Tree SSA, OpenMP, SPEC performance + tracking web pages, GIMPLE tuples, and assorted fixes. + +* David O'Brien for the FreeBSD/alpha, FreeBSD/AMD x86-64, FreeBSD/ARM, + FreeBSD/PowerPC, and FreeBSD/SPARC64 ports and related infrastructure + improvements. + +* Alexandre Oliva for various build infrastructure improvements, scripts and + amazing testing work, including keeping libtool issues sane and happy. + +* Stefan Olsson for work on mt_alloc. + +* Melissa O'Neill for various NeXT fixes. + +* Rainer Orth for random MIPS work, including improvements to GCC's o32 + ABI support, improvements to dejagnu's MIPS support, Java configuration + clean-ups and porting work, and maintaining the IRIX, Solaris 2, and + Tru64 UNIX ports. + +* Steven Pemberton for his contribution of :samp:`enquire` which allowed GCC to + determine various properties of the floating point unit and generate + :samp:`float.h` in older versions of GCC. + +* Hartmut Penner for work on the s390 port. + +* Paul Petersen wrote the machine description for the Alliant FX/8. + +* Alexandre Petit-Bianco for implementing much of the Java compiler and + continued Java maintainership. + +* Matthias Pfaller for major improvements to the NS32k port. + +* Gerald Pfeifer for his direction via the steering committee, pointing + out lots of problems we need to solve, maintenance of the web pages, and + taking care of documentation maintenance in general. + +* Marek Polacek for his work on the C front end, the sanitizers and general + bug fixing. + +* Andrew Pinski for processing bug reports by the dozen. + +* Ovidiu Predescu for his work on the Objective-C front end and runtime + libraries. + +* Jerry Quinn for major performance improvements in C++ formatted I/O. + +* Ken Raeburn for various improvements to checker, MIPS ports and various + cleanups in the compiler. + +* Rolf W. Rasmussen for hacking on AWT. + +* David Reese of Sun Microsystems contributed to the Solaris on PowerPC + port. + +* John Regehr for running automated regression testing of GCC and reporting + numerous bugs. + +* Volker Reichelt for running automated regression testing of GCC and reporting + numerous bugs and for keeping up with the problem reports. + +* Joern Rennecke for maintaining the sh port, loop, regmove & reload + hacking and developing and maintaining the Epiphany port. + +* Loren J. Rittle for improvements to libstdc++-v3 including the FreeBSD + port, threading fixes, thread-related configury changes, critical + threading documentation, and solutions to really tricky I/O problems, + as well as keeping GCC properly working on FreeBSD and continuous testing. + +* Craig Rodrigues for processing tons of bug reports. + +* Ola Rönnerup for work on mt_alloc. + +* Gavin Romig-Koch for lots of behind the scenes MIPS work. + +* David Ronis inspired and encouraged Craig to rewrite the G77 + documentation in texinfo format by contributing a first pass at a + translation of the old :samp:`g77-0.5.16/f/DOC` file. + +* Ken Rose for fixes to GCC's delay slot filling code. + +* Ira Rosen for her contributions to the auto-vectorizer. + +* Paul Rubin wrote most of the preprocessor. + +* Pétur Runólfsson for major performance improvements in C++ formatted I/O and + large file support in C++ filebuf. + +* Chip Salzenberg for libstdc++ patches and improvements to locales, traits, + Makefiles, libio, libtool hackery, and 'long long' support. + +* Juha Sarlin for improvements to the H8 code generator. + +* Greg Satz assisted in making GCC work on HP-UX for the 9000 series 300. + +* Roger Sayle for improvements to constant folding and GCC's RTL optimizers + as well as for fixing numerous bugs. + +* Bradley Schatz for his work on the GCJ FAQ. + +* Peter Schauer wrote the code to allow debugging to work on the Alpha. + +* William Schelter did most of the work on the Intel 80386 support. + +* Tobias Schlüter for work on GNU Fortran. + +* Bernd Schmidt for various code generation improvements and major + work in the reload pass, serving as release manager for + GCC 2.95.3, and work on the Blackfin and C6X ports. + +* Peter Schmid for constant testing of libstdc++---especially application + testing, going above and beyond what was requested for the release + criteria---and libstdc++ header file tweaks. + +* Jason Schroeder for jcf-dump patches. + +* Andreas Schwab for his work on the m68k port. + +* Lars Segerlund for work on GNU Fortran. + +* Dodji Seketeli for numerous C++ bug fixes and debug info improvements. + +* Tim Shen for major work on ````. + +* Joel Sherrill for his direction via the steering committee, RTEMS + contributions and RTEMS testing. + +* Nathan Sidwell for many C++ fixes/improvements. + +* Jeffrey Siegal for helping RMS with the original design of GCC, some + code which handles the parse tree and RTL data structures, constant + folding and help with the original VAX & m68k ports. + +* Kenny Simpson for prompting libstdc++ fixes due to defect reports from + the LWG (thereby keeping GCC in line with updates from the ISO). + +* Franz Sirl for his ongoing work with making the PPC port stable + for GNU/Linux. + +* Andrey Slepuhin for assorted AIX hacking. + +* Trevor Smigiel for contributing the SPU port. + +* Christopher Smith did the port for Convex machines. + +* Danny Smith for his major efforts on the Mingw (and Cygwin) ports. + Retired from GCC maintainership August 2010, having mentored two + new maintainers into the role. + +* Randy Smith finished the Sun FPA support. + +* Ed Smith-Rowland for his continuous work on libstdc++-v3, special functions, + ````, and various improvements to C++11 features. + +* Scott Snyder for queue, iterator, istream, and string fixes and libstdc++ + testsuite entries. Also for providing the patch to G77 to add + rudimentary support for ``INTEGER*1``, ``INTEGER*2``, and + ``LOGICAL*1``. + +* Zdenek Sojka for running automated regression testing of GCC and reporting + numerous bugs. + +* Arseny Solokha for running automated regression testing of GCC and reporting + numerous bugs. + +* Jayant Sonar for contributing the CR16 port. + +* Brad Spencer for contributions to the GLIBCPP_FORCE_NEW technique. + +* Richard Stallman, for writing the original GCC and launching the GNU project. + +* Jan Stein of the Chalmers Computer Society provided support for + Genix, as well as part of the 32000 machine description. + +* Gerhard Steinmetz for running automated regression testing of GCC and reporting + numerous bugs. + +* Nigel Stephens for various mips16 related fixes/improvements. + +* Jonathan Stone wrote the machine description for the Pyramid computer. + +* Graham Stott for various infrastructure improvements. + +* John Stracke for his Java HTTP protocol fixes. + +* Mike Stump for his Elxsi port, G++ contributions over the years and more + recently his vxworks contributions + +* Jeff Sturm for Java porting help, bug fixes, and encouragement. + +* Zhendong Su for running automated regression testing of GCC and reporting + numerous bugs. + +* Chengnian Sun for running automated regression testing of GCC and reporting + numerous bugs. + +* Shigeya Suzuki for this fixes for the bsdi platforms. + +* Ian Lance Taylor for the Go frontend, the initial mips16 and mips64 + support, general configury hacking, fixincludes, etc. + +* Holger Teutsch provided the support for the Clipper CPU. + +* Gary Thomas for his ongoing work to make the PPC work for GNU/Linux. + +* Paul Thomas for contributions to GNU Fortran. + +* Philipp Thomas for random bug fixes throughout the compiler + +* Jason Thorpe for thread support in libstdc++ on NetBSD. + +* Kresten Krab Thorup wrote the run time support for the Objective-C + language and the fantastic Java bytecode interpreter. + +* Michael Tiemann for random bug fixes, the first instruction scheduler, + initial C++ support, function integration, NS32k, SPARC and M88k + machine description work, delay slot scheduling. + +* Andreas Tobler for his work porting libgcj to Darwin. + +* Teemu Torma for thread safe exception handling support. + +* Leonard Tower wrote parts of the parser, RTL generator, and RTL + definitions, and of the VAX machine description. + +* Daniel Towner and Hariharan Sandanagobalane contributed and + maintain the picoChip port. + +* Tom Tromey for internationalization support and for his many Java + contributions and libgcj maintainership. + +* Lassi Tuura for improvements to config.guess to determine HP processor + types. + +* Petter Urkedal for libstdc++ CXXFLAGS, math, and algorithms fixes. + +* Andy Vaught for the design and initial implementation of the GNU Fortran + front end. + +* Brent Verner for work with the libstdc++ cshadow files and their + associated configure steps. + +* Todd Vierling for contributions for NetBSD ports. + +* Andrew Waterman for contributing the RISC-V port, as well as maintaining it. + +* Jonathan Wakely for contributing libstdc++ Doxygen notes and XHTML + guidance and maintaining libstdc++. + +* Dean Wakerley for converting the install documentation from HTML to texinfo + in time for GCC 3.0. + +* Krister Walfridsson for random bug fixes. + +* Feng Wang for contributions to GNU Fortran. + +* Stephen M. Webb for time and effort on making libstdc++ shadow files + work with the tricky Solaris 8+ headers, and for pushing the build-time + header tree. Also, for starting and driving the ```` effort. + +* John Wehle for various improvements for the x86 code generator, + related infrastructure improvements to help x86 code generation, + value range propagation and other work, WE32k port. + +* Ulrich Weigand for work on the s390 port. + +* Janus Weil for contributions to GNU Fortran. + +* Zack Weinberg for major work on cpplib and various other bug fixes. + +* Matt Welsh for help with Linux Threads support in GCJ. + +* Urban Widmark for help fixing java.io. + +* Mark Wielaard for new Java library code and his work integrating with + Classpath. + +* Dale Wiles helped port GCC to the Tahoe. + +* Bob Wilson from Tensilica, Inc. for the Xtensa port. + +* Jim Wilson for his direction via the steering committee, tackling hard + problems in various places that nobody else wanted to work on, strength + reduction and other loop optimizations. + +* Paul Woegerer and Tal Agmon for the CRX port. + +* Carlo Wood for various fixes. + +* Tom Wood for work on the m88k port. + +* Chung-Ju Wu for his work on the Andes NDS32 port. + +* Canqun Yang for work on GNU Fortran. + +* Masanobu Yuhara of Fujitsu Laboratories implemented the machine + description for the Tron architecture (specifically, the Gmicro). + +* Kevin Zachmann helped port GCC to the Tahoe. + +* Ayal Zaks for Swing Modulo Scheduling (SMS). + +* Qirun Zhang for running automated regression testing of GCC and reporting + numerous bugs. + +* Xiaoqiang Zhang for work on GNU Fortran. + +* Gilles Zunino for help porting Java to Irix. + +The following people are recognized for their contributions to GNAT, +the Ada front end of GCC: + +* Bernard Banner + +* Romain Berrendonner + +* Geert Bosch + +* Emmanuel Briot + +* Joel Brobecker + +* Ben Brosgol + +* Vincent Celier + +* Arnaud Charlet + +* Chien Chieng + +* Cyrille Comar + +* Cyrille Crozes + +* Robert Dewar + +* Gary Dismukes + +* Robert Duff + +* Ed Falis + +* Ramon Fernandez + +* Sam Figueroa + +* Vasiliy Fofanov + +* Michael Friess + +* Franco Gasperoni + +* Ted Giering + +* Matthew Gingell + +* Laurent Guerby + +* Jerome Guitton + +* Olivier Hainque + +* Jerome Hugues + +* Hristian Kirtchev + +* Jerome Lambourg + +* Bruno Leclerc + +* Albert Lee + +* Sean McNeil + +* Javier Miranda + +* Laurent Nana + +* Pascal Obry + +* Dong-Ik Oh + +* Laurent Pautet + +* Brett Porter + +* Thomas Quinot + +* Nicolas Roche + +* Pat Rogers + +* Jose Ruiz + +* Douglas Rupp + +* Sergey Rybin + +* Gail Schenker + +* Ed Schonberg + +* Nicolas Setton + +* Samuel Tardieu + +The following people are recognized for their contributions of new +features, bug reports, testing and integration of classpath/libgcj for +GCC version 4.1: + +* Lillian Angel for ``JTree`` implementation and lots Free Swing + additions and bug fixes. + +* Wolfgang Baer for ``GapContent`` bug fixes. + +* Anthony Balkissoon for ``JList``, Free Swing 1.5 updates and mouse event + fixes, lots of Free Swing work including ``JTable`` editing. + +* Stuart Ballard for RMI constant fixes. + +* Goffredo Baroncelli for ``HTTPURLConnection`` fixes. + +* Gary Benson for ``MessageFormat`` fixes. + +* Daniel Bonniot for ``Serialization`` fixes. + +* Chris Burdess for lots of gnu.xml and http protocol fixes, ``StAX`` + and ``DOM xml:id`` support. + +* Ka-Hing Cheung for ``TreePath`` and ``TreeSelection`` fixes. + +* Archie Cobbs for build fixes, VM interface updates, + ``URLClassLoader`` updates. + +* Kelley Cook for build fixes. + +* Martin Cordova for Suggestions for better ``SocketTimeoutException``. + +* David Daney for ``BitSet`` bug fixes, ``HttpURLConnection`` + rewrite and improvements. + +* Thomas Fitzsimmons for lots of upgrades to the gtk+ AWT and Cairo 2D + support. Lots of imageio framework additions, lots of AWT and Free + Swing bug fixes. + +* Jeroen Frijters for ``ClassLoader`` and nio cleanups, serialization fixes, + better ``Proxy`` support, bug fixes and IKVM integration. + +* Santiago Gala for ``AccessControlContext`` fixes. + +* Nicolas Geoffray for ``VMClassLoader`` and ``AccessController`` + improvements. + +* David Gilbert for ``basic`` and ``metal`` icon and plaf support + and lots of documenting, Lots of Free Swing and metal theme + additions. ``MetalIconFactory`` implementation. + +* Anthony Green for ``MIDI`` framework, ``ALSA`` and ``DSSI`` + providers. + +* Andrew Haley for ``Serialization`` and ``URLClassLoader`` fixes, + gcj build speedups. + +* Kim Ho for ``JFileChooser`` implementation. + +* Andrew John Hughes for ``Locale`` and net fixes, URI RFC2986 + updates, ``Serialization`` fixes, ``Properties`` XML support and + generic branch work, VMIntegration guide update. + +* Bastiaan Huisman for ``TimeZone`` bug fixing. + +* Andreas Jaeger for mprec updates. + +* Paul Jenner for better :option:`-Werror` support. + +* Ito Kazumitsu for ``NetworkInterface`` implementation and updates. + +* Roman Kennke for ``BoxLayout``, ``GrayFilter`` and + ``SplitPane``, plus bug fixes all over. Lots of Free Swing work + including styled text. + +* Simon Kitching for ``String`` cleanups and optimization suggestions. + +* Michael Koch for configuration fixes, ``Locale`` updates, bug and + build fixes. + +* Guilhem Lavaux for configuration, thread and channel fixes and Kaffe + integration. JCL native ``Pointer`` updates. Logger bug fixes. + +* David Lichteblau for JCL support library global/local reference + cleanups. + +* Aaron Luchko for JDWP updates and documentation fixes. + +* Ziga Mahkovec for ``Graphics2D`` upgraded to Cairo 0.5 and new regex + features. + +* Sven de Marothy for BMP imageio support, CSS and ``TextLayout`` + fixes. ``GtkImage`` rewrite, 2D, awt, free swing and date/time fixes and + implementing the Qt4 peers. + +* Casey Marshall for crypto algorithm fixes, ``FileChannel`` lock, + ``SystemLogger`` and ``FileHandler`` rotate implementations, NIO + ``FileChannel.map`` support, security and policy updates. + +* Bryce McKinlay for RMI work. + +* Audrius Meskauskas for lots of Free Corba, RMI and HTML work plus + testing and documenting. + +* Kalle Olavi Niemitalo for build fixes. + +* Rainer Orth for build fixes. + +* Andrew Overholt for ``File`` locking fixes. + +* Ingo Proetel for ``Image``, ``Logger`` and ``URLClassLoader`` + updates. + +* Olga Rodimina for ``MenuSelectionManager`` implementation. + +* Jan Roehrich for ``BasicTreeUI`` and ``JTree`` fixes. + +* Julian Scheid for documentation updates and gjdoc support. + +* Christian Schlichtherle for zip fixes and cleanups. + +* Robert Schuster for documentation updates and beans fixes, + ``TreeNode`` enumerations and ``ActionCommand`` and various + fixes, XML and URL, AWT and Free Swing bug fixes. + +* Keith Seitz for lots of JDWP work. + +* Christian Thalinger for 64-bit cleanups, Configuration and VM + interface fixes and ``CACAO`` integration, ``fdlibm`` updates. + +* Gael Thomas for ``VMClassLoader`` boot packages support suggestions. + +* Andreas Tobler for Darwin and Solaris testing and fixing, ``Qt4`` + support for Darwin/OS X, ``Graphics2D`` support, ``gtk+`` + updates. + +* Dalibor Topic for better ``DEBUG`` support, build cleanups and + Kaffe integration. ``Qt4`` build infrastructure, ``SHA1PRNG`` + and ``GdkPixbugDecoder`` updates. + +* Tom Tromey for Eclipse integration, generics work, lots of bug fixes + and gcj integration including coordinating The Big Merge. + +* Mark Wielaard for bug fixes, packaging and release management, + ``Clipboard`` implementation, system call interrupts and network + timeouts and ``GdkPixpufDecoder`` fixes. + +In addition to the above, all of which also contributed time and energy in +testing GCC, we would like to thank the following for their contributions +to testing: + +* Michael Abd-El-Malek + +* Thomas Arend + +* Bonzo Armstrong + +* Steven Ashe + +* Chris Baldwin + +* David Billinghurst + +* Jim Blandy + +* Stephane Bortzmeyer + +* Horst von Brand + +* Frank Braun + +* Rodney Brown + +* Sidney Cadot + +* Bradford Castalia + +* Robert Clark + +* Jonathan Corbet + +* Ralph Doncaster + +* Richard Emberson + +* Levente Farkas + +* Graham Fawcett + +* Mark Fernyhough + +* Robert A. French + +* Jörgen Freyh + +* Mark K. Gardner + +* Charles-Antoine Gauthier + +* Yung Shing Gene + +* David Gilbert + +* Simon Gornall + +* Fred Gray + +* John Griffin + +* Patrik Hagglund + +* Phil Hargett + +* Amancio Hasty + +* Takafumi Hayashi + +* Bryan W. Headley + +* Kevin B. Hendricks + +* Joep Jansen + +* Christian Joensson + +* Michel Kern + +* David Kidd + +* Tobias Kuipers + +* Anand Krishnaswamy + +* A.O.V. Le Blanc + +* llewelly + +* Damon Love + +* Brad Lucier + +* Matthias Klose + +* Martin Knoblauch + +* Rick Lutowski + +* Jesse Macnish + +* Stefan Morrell + +* Anon A. Mous + +* Matthias Mueller + +* Pekka Nikander + +* Rick Niles + +* Jon Olson + +* Magnus Persson + +* Chris Pollard + +* Richard Polton + +* Derk Reefman + +* David Rees + +* Paul Reilly + +* Tom Reilly + +* Torsten Rueger + +* Danny Sadinoff + +* Marc Schifer + +* Erik Schnetter + +* Wayne K. Schroll + +* David Schuler + +* Vin Shelton + +* Tim Souder + +* Adam Sulmicki + +* Bill Thorson + +* George Talbot + +* Pedro A. M. Vazquez + +* Gregory Warnes + +* Ian Watson + +* David E. Young + +* And many others + +And finally we'd like to thank everyone who uses the compiler, provides +feedback and generally reminds us why we're doing this work in the first +place. \ No newline at end of file diff --git a/doc/contribute.rst b/doc/contribute.rst new file mode 100644 index 00000000000..643562efc63 --- /dev/null +++ b/doc/contribute.rst @@ -0,0 +1,21 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _contributing: + +Contributing to GCC Development +------------------------------- + +If you would like to help pretest GCC releases to assure they work well, +current development sources are available via Git (see +https://gcc.gnu.org/git.html). Source and binary snapshots are +also available for FTP; see https://gcc.gnu.org/snapshots.html. + +If you would like to work on improvements to GCC, please read the +advice at these URLs: https://gcc.gnu.org/contribute.html, https://gcc.gnu.org/contributewhy.html. + +for information on how to make useful contributions and avoid +duplication of effort. Suggested projects are listed at +https://gcc.gnu.org/projects/. \ No newline at end of file diff --git a/doc/cppdiropts.rst b/doc/cppdiropts.rst new file mode 100644 index 00000000000..91568fe5612 --- /dev/null +++ b/doc/cppdiropts.rst @@ -0,0 +1,217 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. option:: -I {dir}, -iquote {dir}, -isystem {dir}, -idirafter {dir} + + Add the directory :samp:`{dir}` to the list of directories to be searched + for header files during preprocessing. + + .. only:: cpp + + See :ref:`search-path`. + + If :samp:`{dir}` begins with :samp:`=` or ``$SYSROOT``, then the :samp:`=` + or ``$SYSROOT`` is replaced by the sysroot prefix; see + :option:`--sysroot` and :option:`-isysroot`. + + Directories specified with :option:`-iquote` apply only to the quote + form of the directive, ``#include "file"``. + Directories specified with :option:`-I`, :option:`-isystem`, + or :option:`-idirafter` apply to lookup for both the + ``#include "file"`` and + ``#include `` directives. + + You can specify any number or combination of these options on the + command line to search for header files in several directories. + The lookup order is as follows: + + * For the quote form of the include directive, the directory of the current + file is searched first. + + * For the quote form of the include directive, the directories specified + by :option:`-iquote` options are searched in left-to-right order, + as they appear on the command line. + + * Directories specified with :option:`-I` options are scanned in + left-to-right order. + + * Directories specified with :option:`-isystem` options are scanned in + left-to-right order. + + * Standard system directories are scanned. + + * Directories specified with :option:`-idirafter` options are scanned in + left-to-right order. + + You can use :option:`-I` to override a system header + file, substituting your own version, since these directories are + searched before the standard system header file directories. + However, you should + not use this option to add directories that contain vendor-supplied + system header files; use :option:`-isystem` for that. + + The :option:`-isystem` and :option:`-idirafter` options also mark the directory + as a system directory, so that it gets the same special treatment that + is applied to the standard system directories. + + .. only:: cpp + + See :ref:`system-headers`. + + + If a standard system include directory, or a directory specified with + :option:`-isystem`, is also specified with :option:`-I`, the :option:`-I` + option is ignored. The directory is still searched but as a + system directory at its normal position in the system include chain. + This is to ensure that GCC's procedure to fix buggy system headers and + the ordering for the ``#include_next`` directive are not inadvertently + changed. + If you really need to change the search order for system directories, + use the :option:`-nostdinc` and/or :option:`-isystem` options. + + .. only:: cpp + + See :ref:`system-headers`. + + +.. option:: -I- + + Split the include path. + This option has been deprecated. Please use :option:`-iquote` instead for + :option:`-I` directories before the :option:`-I-` and remove the :option:`-I-` + option. + + Any directories specified with :option:`-I` + options before :option:`-I-` are searched only for headers requested with + ``#include "file"`` ; they are not searched for + ``#include ``. If additional directories are + specified with :option:`-I` options after the :option:`-I-`, those + directories are searched for all :samp:`#include` directives. + + In addition, :option:`-I-` inhibits the use of the directory of the current + file directory as the first search directory for ``#include + "file"``. There is no way to override this effect of :option:`-I-`. + + .. only:: cpp + + See :ref:`search-path`. + + +.. option:: -iprefix {prefix} + + Specify :samp:`{prefix}` as the prefix for subsequent :option:`-iwithprefix` + options. If the prefix represents a directory, you should include the + final :samp:`/`. + +.. option:: -iwithprefix {dir}, -iwithprefixbefore {dir} + + Append :samp:`{dir}` to the prefix specified previously with + :option:`-iprefix`, and add the resulting directory to the include search + path. :option:`-iwithprefixbefore` puts it in the same place :option:`-I` + would; :option:`-iwithprefix` puts it where :option:`-idirafter` would. + +.. option:: -isysroot {dir} + + This option is like the :option:`--sysroot` option, but applies only to + header files (except for Darwin targets, where it applies to both header + files and libraries). See the :option:`--sysroot` option for more + information. + +.. option:: -imultilib {dir} + + Use :samp:`{dir}` as a subdirectory of the directory containing + target-specific C++ headers. + +.. option:: -nostdinc + + Do not search the standard system directories for header files. + Only the directories explicitly specified with :option:`-I`, + :option:`-iquote`, :option:`-isystem`, and/or :option:`-idirafter` + options (and the directory of the current file, if appropriate) + are searched. + +.. option:: -nostdinc++ + + Do not search for header files in the C++-specific standard directories, + but do still search the other standard directories. (This option is + used when building the C++ library.) + +.. option:: -Wcomment, -Wcomments + + Warn whenever a comment-start sequence :samp:`/*` appears in a :samp:`/*` + comment, or whenever a backslash-newline appears in a :samp:`//` comment. + This warning is enabled by :option:`-Wall`. + +.. option:: -Wtrigraphs + +.. _wtrigraphs: + + Warn if any trigraphs are encountered that might change the meaning of + the program. Trigraphs within comments are not warned about, + except those that would form escaped newlines. + + This option is implied by :option:`-Wall`. If :option:`-Wall` is not + given, this option is still enabled unless trigraphs are enabled. To + get trigraph conversion without warnings, but get the other + :option:`-Wall` warnings, use :samp:`-trigraphs -Wall -Wno-trigraphs`. + +.. option:: -Wundef + + Warn if an undefined identifier is evaluated in an ``#if`` directive. + Such identifiers are replaced with zero. + +.. option:: -Wno-undef + + Default setting; overrides :option:`-Wundef`. + +.. option:: -Wexpansion-to-defined + + Warn whenever :samp:`defined` is encountered in the expansion of a macro + (including the case where the macro is expanded by an :samp:`#if` directive). + Such usage is not portable. + This warning is also enabled by :option:`-Wpedantic` and :option:`-Wextra`. + +.. option:: -Wunused-macros + + Warn about macros defined in the main file that are unused. A macro + is :dfn:`used` if it is expanded or tested for existence at least once. + The preprocessor also warns if the macro has not been used at the + time it is redefined or undefined. + + Built-in macros, macros defined on the command line, and macros + defined in include files are not warned about. + + .. note:: + + If a macro is actually used, but only used in skipped + conditional blocks, then the preprocessor reports it as unused. To avoid the + warning in such a case, you might improve the scope of the macro's + definition by, for example, moving it into the first skipped block. + Alternatively, you could provide a dummy use with something like: + + .. code-block:: c++ + + #if defined the_macro_causing_the_warning + #endif + +.. option:: -Wno-endif-labels + + Do not warn whenever an ``#else`` or an ``#endif`` are followed by text. + This sometimes happens in older programs with code of the form + + .. code-block:: c++ + + #if FOO + ... + #else FOO + ... + #endif FOO + + The second and third ``FOO`` should be in comments. + This warning is on by default. + +.. option:: -Wendif-labels + + Default setting; overrides :option:`-Wno-endif-labels`. \ No newline at end of file diff --git a/doc/cppenv.rst b/doc/cppenv.rst new file mode 100644 index 00000000000..f27338cfa2f --- /dev/null +++ b/doc/cppenv.rst @@ -0,0 +1,97 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. envvar:: CPATH, C_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJC_INCLUDE_PATH + + .. Commented out until ObjC++ is part of GCC: + @itemx OBJCPLUS_INCLUDE_PATH + + Each variable's value is a list of directories separated by a special + character, much like :envvar:`PATH`, in which to look for header files. + The special character, ``PATH_SEPARATOR``, is target-dependent and + determined at GCC build time. For Microsoft Windows-based targets it is a + semicolon, and for almost all other targets it is a colon. + + :envvar:`CPATH` specifies a list of directories to be searched as if + specified with :option:`-I`, but after any paths given with :option:`-I` + options on the command line. This environment variable is used + regardless of which language is being preprocessed. + + The remaining environment variables apply only when preprocessing the + particular language indicated. Each specifies a list of directories + to be searched as if specified with :option:`-isystem`, but after any + paths given with :option:`-isystem` options on the command line. + + In all these variables, an empty element instructs the compiler to + search its current working directory. Empty elements can appear at the + beginning or end of a path. For instance, if the value of + :envvar:`CPATH` is ``:/special/include``, that has the same + effect as :samp:`-I. -I/special/include`. + + .. only:: cpp + + See also :ref:`search-path`. + +.. index:: dependencies for make as output + +.. envvar:: DEPENDENCIES_OUTPUT + + If this variable is set, its value specifies how to output + dependencies for Make based on the non-system header files processed + by the compiler. System header files are ignored in the dependency + output. + + The value of :envvar:`DEPENDENCIES_OUTPUT` can be just a file name, in + which case the Make rules are written to that file, guessing the target + name from the source file name. Or the value can have the form + :samp:`{file}{target}`, in which case the rules are written to + file :samp:`{file}` using :samp:`{target}` as the target name. + + In other words, this environment variable is equivalent to combining + the options :option:`-MM` and :option:`-MF` + + .. only:: cpp + + (see :ref:`invocation`), + + .. only:: not cpp + + (see :ref:`preprocessor-options`), + + with an optional :option:`-MT` switch too. + +.. index:: dependencies for make as output + +.. envvar:: SUNPRO_DEPENDENCIES + + This variable is the same as :envvar:`DEPENDENCIES_OUTPUT` (see above), + except that system header files are not ignored, so it implies + :option:`-M` rather than :option:`-MM`. However, the dependence on the + main input file is omitted. + + .. only:: cpp + + See :ref:`invocation`. + + .. only:: not cpp + + See :ref:`preprocessor-options`. + +.. envvar:: SOURCE_DATE_EPOCH + + If this variable is set, its value specifies a UNIX timestamp to be + used in replacement of the current date and time in the ``__DATE__`` + and ``__TIME__`` macros, so that the embedded timestamps become + reproducible. + + The value of :envvar:`SOURCE_DATE_EPOCH` must be a UNIX timestamp, + defined as the number of seconds (excluding leap seconds) since + 01 Jan 1970 00:00:00 represented in ASCII; identical to the output of + ``date +%s`` on GNU/Linux and other systems that support the + ``%s`` extension in the ``date`` command. + + The value should be a known timestamp such as the last modification + time of the source or package and it should be set by the build + process. \ No newline at end of file diff --git a/doc/cppopts.rst b/doc/cppopts.rst new file mode 100644 index 00000000000..60d663e35d8 --- /dev/null +++ b/doc/cppopts.rst @@ -0,0 +1,556 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. option:: -D {name} + + Predefine :samp:`{name}` as a macro, with definition ``1``. + +.. option:: -D name=definition + + The contents of :samp:`{definition}` are tokenized and processed as if + they appeared during translation phase three in a :samp:`#define` + directive. In particular, the definition is truncated by + embedded newline characters. + + If you are invoking the preprocessor from a shell or shell-like + program you may need to use the shell's quoting syntax to protect + characters such as spaces that have a meaning in the shell syntax. + + If you wish to define a function-like macro on the command line, write + its argument list with surrounding parentheses before the equals sign + (if any). Parentheses are meaningful to most shells, so you should + quote the option. With :command:`sh` and :command:`csh`, + :option:`-D'name(args...)=definition'` works. + + :option:`-D` and :option:`-U` options are processed in the order they + are given on the command line. All :option:`-imacros file` and + :option:`-include file` options are processed after all + :option:`-D` and :option:`-U` options. + +.. option:: -U {name} + + Cancel any previous definition of :samp:`{name}`, either built in or + provided with a :option:`-D` option. + +.. option:: -include {file} + + Process :samp:`{file}` as if ``#include "file"`` appeared as the first + line of the primary source file. However, the first directory searched + for :samp:`{file}` is the preprocessor's working directory *instead of* + the directory containing the main source file. If not found there, it + is searched for in the remainder of the ``#include "..."`` search + chain as normal. + + If multiple :option:`-include` options are given, the files are included + in the order they appear on the command line. + +.. option:: -imacros {file} + + Exactly like :option:`-include`, except that any output produced by + scanning :samp:`{file}` is thrown away. Macros it defines remain defined. + This allows you to acquire all the macros from a header without also + processing its declarations. + + All files specified by :option:`-imacros` are processed before all files + specified by :option:`-include`. + +.. option:: -undef + + Do not predefine any system-specific or GCC-specific macros. The + standard predefined macros remain defined. + + .. only:: cpp + + See :ref:`standard-predefined-macros`. + +.. option:: -pthread + + Define additional macros required for using the POSIX threads library. + You should use this option consistently for both compilation and linking. + This option is supported on GNU/Linux targets, most other Unix derivatives, + and also on x86 Cygwin and MinGW targets. + +.. index:: make, dependencies, make + +.. option:: -M + + Instead of outputting the result of preprocessing, output a rule + suitable for :command:`make` describing the dependencies of the main + source file. The preprocessor outputs one :command:`make` rule containing + the object file name for that source file, a colon, and the names of all + the included files, including those coming from :option:`-include` or + :option:`-imacros` command-line options. + + Unless specified explicitly (with :option:`-MT` or :option:`-MQ`), the + object file name consists of the name of the source file with any + suffix replaced with object file suffix and with any leading directory + parts removed. If there are many included files then the rule is + split into several lines using :samp:`\\` -newline. The rule has no + commands. + + This option does not suppress the preprocessor's debug output, such as + :option:`-dM`. To avoid mixing such debug output with the dependency + rules you should explicitly specify the dependency output file with + :option:`-MF`, or use an environment variable like + :envvar:`DEPENDENCIES_OUTPUT` (see :ref:`environment-variables`). Debug output + is still sent to the regular output stream as normal. + + Passing :option:`-M` to the driver implies :option:`-E`, and suppresses + warnings with an implicit :option:`-w`. + +.. option:: -MM + + Like :option:`-M` but do not mention header files that are found in + system header directories, nor header files that are included, + directly or indirectly, from such a header. + + This implies that the choice of angle brackets or double quotes in an + :samp:`#include` directive does not in itself determine whether that + header appears in :option:`-MM` dependency output. + +.. option:: -MF {file} + + When used with :option:`-M` or :option:`-MM`, specifies a + file to write the dependencies to. If no :option:`-MF` switch is given + the preprocessor sends the rules to the same place it would send + preprocessed output. + + When used with the driver options :option:`-MD` or :option:`-MMD`, + :option:`-MF` overrides the default dependency output file. + + If :samp:`{file}` is :samp:`-`, then the dependencies are written to :samp:`stdout`. + +.. option:: -MG + + In conjunction with an option such as :option:`-M` requesting + dependency generation, :option:`-MG` assumes missing header files are + generated files and adds them to the dependency list without raising + an error. The dependency filename is taken directly from the + ``#include`` directive without prepending any path. :option:`-MG` + also suppresses preprocessed output, as a missing header file renders + this useless. + + This feature is used in automatic updating of makefiles. + +.. option:: -Mno-modules + + Disable dependency generation for compiled module interfaces. + +.. option:: -MP + + This option instructs CPP to add a phony target for each dependency + other than the main file, causing each to depend on nothing. These + dummy rules work around errors :command:`make` gives if you remove header + files without updating the :samp:`Makefile` to match. + + This is typical output: + + .. code-block:: c++ + + test.o: test.c test.h + + test.h: + +.. option:: -MT {target} + + Change the target of the rule emitted by dependency generation. By + default CPP takes the name of the main input file, deletes any + directory components and any file suffix such as :samp:`.c`, and + appends the platform's usual object suffix. The result is the target. + + An :option:`-MT` option sets the target to be exactly the string you + specify. If you want multiple targets, you can specify them as a single + argument to :option:`-MT`, or use multiple :option:`-MT` options. + + For example, ``-MT '$(objpfx)foo.o'`` might give + + .. code-block:: c++ + + $(objpfx)foo.o: foo.c + +.. option:: -MQ {target} + + Same as :option:`-MT`, but it quotes any characters which are special to + Make. ``-MQ '$(objpfx)foo.o'`` gives + + .. code-block:: c++ + + $$(objpfx)foo.o: foo.c + + The default target is automatically quoted, as if it were given with + :option:`-MQ`. + +.. option:: -MD + + :option:`-MD` is equivalent to :option:`-M -MF file`, except that + :option:`-E` is not implied. The driver determines :samp:`{file}` based on + whether an :option:`-o` option is given. If it is, the driver uses its + argument but with a suffix of :samp:`.d`, otherwise it takes the name + of the input file, removes any directory components and suffix, and + applies a :samp:`.d` suffix. + + If :option:`-MD` is used in conjunction with :option:`-E`, any + :option:`-o` switch is understood to specify the dependency output file + (see :option:`-MF`), but if used without :option:`-E`, each :option:`-o` + is understood to specify a target object file. + + Since :option:`-E` is not implied, :option:`-MD` can be used to generate + a dependency output file as a side effect of the compilation process. + +.. option:: -MMD + + Like :option:`-MD` except mention only user header files, not system + header files. + +.. option:: -fpreprocessed + + Indicate to the preprocessor that the input file has already been + preprocessed. This suppresses things like macro expansion, trigraph + conversion, escaped newline splicing, and processing of most directives. + The preprocessor still recognizes and removes comments, so that you can + pass a file preprocessed with :option:`-C` to the compiler without + problems. In this mode the integrated preprocessor is little more than + a tokenizer for the front ends. + + :option:`-fpreprocessed` is implicit if the input file has one of the + extensions :samp:`.i`, :samp:`.ii` or :samp:`.mi`. These are the + extensions that GCC uses for preprocessed files created by + :option:`-save-temps`. + +.. option:: -fdirectives-only + + When preprocessing, handle directives, but do not expand macros. + + The option's behavior depends on the :option:`-E` and :option:`-fpreprocessed` + options. + + With :option:`-E`, preprocessing is limited to the handling of directives + such as ``#define``, ``#ifdef``, and ``#error``. Other + preprocessor operations, such as macro expansion and trigraph + conversion are not performed. In addition, the :option:`-dD` option is + implicitly enabled. + + With :option:`-fpreprocessed`, predefinition of command line and most + builtin macros is disabled. Macros such as ``__LINE__``, which are + contextually dependent, are handled normally. This enables compilation of + files previously preprocessed with ``-E -fdirectives-only``. + + With both :option:`-E` and :option:`-fpreprocessed`, the rules for + :option:`-fpreprocessed` take precedence. This enables full preprocessing of + files previously preprocessed with ``-E -fdirectives-only``. + +.. option:: -fdollars-in-identifiers + + Accept :samp:`$` in identifiers. + + .. only:: cpp + + See :ref:`identifier-characters`. + +.. option:: -fextended-identifiers + + Accept universal character names and extended characters in + identifiers. This option is enabled by default for C99 (and later C + standard versions) and C++. + +.. option:: -fno-canonical-system-headers + + When preprocessing, do not shorten system header paths with canonicalization. + +.. option:: -fmax-include-depth={depth} + + Set the maximum depth of the nested #include. The default is 200. + +.. option:: -ftabstop={width} + + Set the distance between tab stops. This helps the preprocessor report + correct column numbers in warnings or errors, even if tabs appear on the + line. If the value is less than 1 or greater than 100, the option is + ignored. The default is 8. + +.. option:: -ftrack-macro-expansion[={level}] + + Track locations of tokens across macro expansions. This allows the + compiler to emit diagnostic about the current macro expansion stack + when a compilation error occurs in a macro expansion. Using this + option makes the preprocessor and the compiler consume more + memory. The :samp:`{level}` parameter can be used to choose the level of + precision of token location tracking thus decreasing the memory + consumption if necessary. Value :samp:`0` of :samp:`{level}` de-activates + this option. Value :samp:`1` tracks tokens locations in a + degraded mode for the sake of minimal memory overhead. In this mode + all tokens resulting from the expansion of an argument of a + function-like macro have the same location. Value :samp:`2` tracks + tokens locations completely. This value is the most memory hungry. + When this option is given no argument, the default parameter value is + :samp:`2`. + + Note that ``-ftrack-macro-expansion=2`` is activated by default. + +.. option:: -fmacro-prefix-map={old}={new} + + When preprocessing files residing in directory :samp:`{old}`, + expand the ``__FILE__`` and ``__BASE_FILE__`` macros as if the + files resided in directory :samp:`{new}` instead. This can be used + to change an absolute path to a relative path by using :samp:`.` for + :samp:`{new}` which can result in more reproducible builds that are + location independent. This option also affects + ``__builtin_FILE()`` during compilation. See also + :option:`-ffile-prefix-map`. + +.. index:: character set, execution + +.. option:: -fexec-charset={charset} + + Set the execution character set, used for string and character + constants. The default is UTF-8. :samp:`{charset}` can be any encoding + supported by the system's ``iconv`` library routine. + +.. index:: character set, wide execution + +.. option:: -fwide-exec-charset={charset} + + Set the wide execution character set, used for wide string and + character constants. The default is one of UTF-32BE, UTF-32LE, UTF-16BE, + or UTF-16LE, whichever corresponds to the width of ``wchar_t`` and the + big-endian or little-endian byte order being used for code generation. As + with :option:`-fexec-charset`, :samp:`{charset}` can be any encoding supported + by the system's ``iconv`` library routine; however, you will have + problems with encodings that do not fit exactly in ``wchar_t``. + +.. index:: character set, input + +.. option:: -finput-charset={charset} + + Set the input character set, used for translation from the character + set of the input file to the source character set used by GCC. If the + locale does not specify, or GCC cannot get this information from the + locale, the default is UTF-8. This can be overridden by either the locale + or this command-line option. Currently the command-line option takes + precedence if there's a conflict. :samp:`{charset}` can be any encoding + supported by the system's ``iconv`` library routine. + +.. only:: not cpp + + .. option:: -fpch-deps + + When using precompiled headers (see :ref:`precompiled-headers`), this flag + causes the dependency-output flags to also list the files from the + precompiled header's dependencies. If not specified, only the + precompiled header are listed and not the files that were used to + create it, because those files are not consulted when a precompiled + header is used. + + .. option:: -fpch-preprocess + + This option allows use of a precompiled header (see :ref:`precompiled-headers`) together with :option:`-E`. It inserts a special ``#pragma``, + ``#pragma GCC pch_preprocess "filename"`` in the output to mark + the place where the precompiled header was found, and its :samp:`{filename}`. + When :option:`-fpreprocessed` is in use, GCC recognizes this ``#pragma`` + and loads the PCH. + + This option is off by default, because the resulting preprocessed output + is only really suitable as input to GCC. It is switched on by + :option:`-save-temps`. + + You should not write this ``#pragma`` in your own code, but it is + safe to edit the filename if the PCH file is available in a different + location. The filename may be absolute or it may be relative to GCC's + current directory. + +.. option:: -fworking-directory + + Enable generation of linemarkers in the preprocessor output that + let the compiler know the current working directory at the time of + preprocessing. When this option is enabled, the preprocessor + emits, after the initial linemarker, a second linemarker with the + current working directory followed by two slashes. GCC uses this + directory, when it's present in the preprocessed input, as the + directory emitted as the current working directory in some debugging + information formats. This option is implicitly enabled if debugging + information is enabled, but this can be inhibited with the negated + form :option:`-fno-working-directory`. If the :option:`-P` flag is + present in the command line, this option has no effect, since no + ``#line`` directives are emitted whatsoever. + +.. option:: -fno-working-directory + + Default setting; overrides :option:`-fworking-directory`. + +.. option:: -A {predicate}={answer} + + Make an assertion with the predicate :samp:`{predicate}` and answer + :samp:`{answer}`. This form is preferred to the older form :option:`-A + predicate(answer)`, which is still supported, because + it does not use shell special characters. + + .. only:: cpp + + See :ref:`obsolete-features`. + +.. option:: -A -predicate=answer + + Cancel an assertion with the predicate :samp:`{predicate}` and answer + :samp:`{answer}`. + +.. option:: -C + + Do not discard comments. All comments are passed through to the output + file, except for comments in processed directives, which are deleted + along with the directive. + + You should be prepared for side effects when using :option:`-C` ; it + causes the preprocessor to treat comments as tokens in their own right. + For example, comments appearing at the start of what would be a + directive line have the effect of turning that line into an ordinary + source line, since the first token on the line is no longer a :samp:`#`. + +.. option:: -CC + + Do not discard comments, including during macro expansion. This is + like :option:`-C`, except that comments contained within macros are + also passed through to the output file where the macro is expanded. + + In addition to the side effects of the :option:`-C` option, the + :option:`-CC` option causes all C++-style comments inside a macro + to be converted to C-style comments. This is to prevent later use + of that macro from inadvertently commenting out the remainder of + the source line. + + The :option:`-CC` option is generally used to support lint comments. + +.. option:: -P + + Inhibit generation of linemarkers in the output from the preprocessor. + This might be useful when running the preprocessor on something that is + not C code, and will be sent to a program which might be confused by the + linemarkers. + + .. only:: cpp + + See :ref:`preprocessor-output`. + + .. index:: traditional C language, C language, traditional + +.. option:: -traditional, -traditional-cpp + + Try to imitate the behavior of pre-standard C preprocessors, as + opposed to ISO C preprocessors. + + .. only:: cpp + + See :ref:`traditional-mode`. + + .. only:: not cpp + + See the GNU CPP manual for details. + + Note that GCC does not otherwise attempt to emulate a pre-standard + C compiler, and these options are only supported with the :option:`-E` + switch, or when invoking CPP explicitly. + +.. option:: -trigraphs + + Support ISO C trigraphs. + These are three-character sequences, all starting with :samp:`??`, that + are defined by ISO C to stand for single characters. For example, + :samp:`??/` stands for :samp:`\\`, so :samp:`??/n` is a character + constant for a newline. + + .. only:: cpp + + See :ref:`initial-processing`. + + .. only:: not cpp + + The nine trigraphs and their replacements are + + .. code-block:: + + Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- + Replacement: [ ] { } # \ ^ | ~ + + By default, GCC ignores trigraphs, but in + standard-conforming modes it converts them. See the :option:`-std` and + :option:`-ansi` options. + +.. option:: -remap + + Enable special code to work around file systems which only permit very + short file names, such as MS-DOS. + +.. option:: -H + + Print the name of each header file used, in addition to other normal + activities. Each name is indented to show how deep in the + :samp:`#include` stack it is. Precompiled header files are also + printed, even if they are found to be invalid; an invalid precompiled + header file is printed with :samp:`...x` and a valid one with :samp:`...!` . + +.. option:: -dletters + + Says to make debugging dumps during compilation as specified by + :samp:`{letters}`. The flags documented here are those relevant to the + preprocessor. Other :samp:`{letters}` are interpreted + by the compiler proper, or reserved for future versions of GCC, and so + are silently ignored. If you specify :samp:`{letters}` whose behavior + conflicts, the result is undefined. + + .. only:: not cpp + + See :ref:`developer-options`, for more information. + + .. option:: -dM + + Instead of the normal output, generate a list of :samp:`#define` + directives for all the macros defined during the execution of the + preprocessor, including predefined macros. This gives you a way of + finding out what is predefined in your version of the preprocessor. + Assuming you have no file :samp:`foo.h`, the command + + .. code-block:: c++ + + touch foo.h; cpp -dM foo.h + + shows all the predefined macros. + + .. only:: cpp + + If you use :option:`-dM` without the :option:`-E` option, :option:`-dM` is + interpreted as a synonym for :option:`-fdump-rtl-mach`. + See :ref:`developer-options`. + + .. option:: -dD + + Like :option:`-dM` except in two respects: it does *not* include the + predefined macros, and it outputs *both* the :samp:`#define` + directives and the result of preprocessing. Both kinds of output go to + the standard output file. + + .. option:: -dN + + Like :option:`-dD`, but emit only the macro names, not their expansions. + + .. option:: -dI + + Output :samp:`#include` directives in addition to the result of + preprocessing. + + .. option:: -dU + + Like :option:`-dD` except that only macros that are expanded, or whose + definedness is tested in preprocessor directives, are output; the + output is delayed until the use or test of the macro; and + :samp:`#undef` directives are also output for macros tested but + undefined at the time. + +.. option:: -fdebug-cpp + + This option is only useful for debugging GCC. When used from CPP or with + :option:`-E`, it dumps debugging information about location maps. Every + token in the output is preceded by the dump of the map its location + belongs to. + + When used from GCC without :option:`-E`, this option has no effect. \ No newline at end of file diff --git a/doc/cppwarnopts.rst b/doc/cppwarnopts.rst new file mode 100644 index 00000000000..8e9e9e7276f --- /dev/null +++ b/doc/cppwarnopts.rst @@ -0,0 +1,4 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. \ No newline at end of file diff --git a/doc/favicon.ico b/doc/favicon.ico new file mode 100644 index 00000000000..42e8969edc8 Binary files /dev/null and b/doc/favicon.ico differ diff --git a/doc/funding.rst b/doc/funding.rst new file mode 100644 index 00000000000..ee4daca6fd7 --- /dev/null +++ b/doc/funding.rst @@ -0,0 +1,47 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +Funding Free Software +===================== + +If you want to have more free software a few years from now, it makes +sense for you to help encourage people to contribute funds for its +development. The most effective approach known is to encourage +commercial redistributors to donate. + +Users of free software systems can boost the pace of development by +encouraging for-a-fee distributors to donate part of their selling price +to free software developers-the Free Software Foundation, and others. + +The way to convince distributors to do this is to demand it and expect +it from them. So when you compare distributors, judge them partly by +how much they give to free software development. Show distributors +they must compete to be the one who gives the most. + +To make this approach work, you must insist on numbers that you can +compare, such as, 'We will donate ten dollars to the Frobnitz project +for each disk sold.' Don't be satisfied with a vague promise, such as +'A portion of the profits are donated,' since it doesn't give a basis +for comparison. + +Even a precise fraction 'of the profits from this disk' is not very +meaningful, since creative accounting and unrelated business decisions +can greatly alter what fraction of the sales price counts as profit. +If the price you pay is $50, ten percent of the profit is probably +less than a dollar; it might be a few cents, or nothing at all. + +Some redistributors do development work themselves. This is useful too; +but to keep everyone honest, you need to inquire how much they do, and +what kind. Some kinds of development make much more long-term +difference than others. For example, maintaining a separate version of +a program contributes very little; maintaining the standard version of a +program for the whole community contributes much. Easy new ports +contribute little, since someone else would surely do them; difficult +ports such as adding a new CPU to the GNU Compiler Collection contribute more; +major new features or packages contribute the most. + +By establishing the idea that supporting further development is 'the +proper thing to do' when distributing free software for a fee, we can +assure a steady flow of resources into making more free software. \ No newline at end of file diff --git a/doc/gcc_sphinx.py b/doc/gcc_sphinx.py new file mode 100644 index 00000000000..2ef15aef944 --- /dev/null +++ b/doc/gcc_sphinx.py @@ -0,0 +1,44 @@ +# GCC Sphinx customization + +__version__ = '1.0' + + +def setup(app): + app.add_object_type('gcc-attr', 'gcc-attr', objname='GCC attribute', + indextemplate='pair: %s; attribute') + app.add_object_type('fn-attr', 'fn-attr', objname='function attribute', + indextemplate='pair: %s; function attribute') + app.add_object_type('var-attr', 'var-attr', objname='variable attribute', + indextemplate='pair: %s; variable attribute') + app.add_object_type('type-attr', 'type-attr', objname='type attribute', + indextemplate='pair: %s; variable attribute') + app.add_object_type('enum-attr', 'enum-attr', objname='Enumerator attribute', + indextemplate='pair: %s; enumerator attribute') + app.add_object_type('label-attr', 'label-attr', objname='Label attribute', + indextemplate='pair: %s; label attribute') + app.add_object_type('gcc-param', 'gcc-param', objname='GCC parameter', + indextemplate='pair: %s; parameter') + + targets = (('AArch64 ', 'aarch64'), ('AMD GCN ', 'amd-gcn'), ('ARC ', 'arc'), ('ARM ', 'arm'), ('AVR ', 'avr'), + ('Blackfin ', 'blackfin'), ('BPF ', 'bpf'), ('C-SKY ', 'c-sky'), + ('Epiphany ', 'epiphany'), ('H8/300 ', 'h8-300'), ('IA-64 ', 'ia-64'), ('LoongArch', 'loongarch'), ('M32C ', 'm32c'), + ('M32R/D ', 'm32r-d'), ('m68k ', 'm68k'), ('MCORE ', 'mcore'), ('MeP ', 'mep'), + ('MicroBlaze ', 'microblaze'), ('Microsoft Windows ', 'microsoft-windows'), ('MIPS ', 'mips'), + ('MSP430 ', 'msp430'), ('NDS32 ', 'nds32'), ('Nios II ', 'nios-ii'), ('Nvidia PTX ', 'nvidia-ptx'), + ('PowerPC ', 'powerpc'), ('RISC-V ', 'risc-v'), ('RL78 ', 'rl78'), ('RX ', 'rx'), ('S/390 ', 's-390'), + ('SH ', 'sh'), ('Symbian OS ', 'symbian-os'), ('V850 ', 'v850'), ('Visium ', 'visium'), ('x86 ', 'x86'), + ('Xstormy16 ', 'xstormy16')) + + for target_name, target in targets: + app.add_object_type(f'{target}-fn-attr', f'{target}-fn-attr', objname=f'{target_name} function attribute', + indextemplate=f'pair: %s; {target_name} function attribute') + app.add_object_type(f'{target}-var-attr', f'{target}-var-attr', objname=f'{target_name} variable attribute', + indextemplate=f'pair: %s; {target_name} variable attribute') + app.add_object_type(f'{target}-type-attr', f'{target}-type-attr', objname=f'{target_name} type attribute', + indextemplate=f'pair: %s; {target_name} type attribute') + + return dict( + version=__version__, + parallel_read_safe=True, + parallel_write_safe=True + ) diff --git a/doc/gnu.rst b/doc/gnu.rst new file mode 100644 index 00000000000..930659b250b --- /dev/null +++ b/doc/gnu.rst @@ -0,0 +1,19 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _gnu-project: + +The GNU Project and GNU/Linux +============================= + +The GNU Project was launched in 1984 to develop a complete Unix-like +operating system which is free software: the GNU system. (GNU is a +recursive acronym for 'GNU's Not Unix'; it is pronounced +'guh-NEW'.) Variants of the GNU operating system, which use the +kernel Linux, are now widely used; though these systems are often +referred to as 'Linux', they are more accurately called GNU/Linux +systems. + +For more information, see: https://www.gnu.org/ and https://www.gnu.org/gnu/linux-and-gnu.html. \ No newline at end of file diff --git a/doc/gnu_free_documentation_license.rst b/doc/gnu_free_documentation_license.rst new file mode 100644 index 00000000000..5a7d110efde --- /dev/null +++ b/doc/gnu_free_documentation_license.rst @@ -0,0 +1,476 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _gnu_fdl: + +****************************** +GNU Free Documentation License +****************************** + +Version 1.3, 3 November 2008 + +Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc +https://fsf.org/ + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + +Preamble +~~~~~~~~ + +The purpose of this License is to make a manual, textbook, or other +functional and useful document "free" in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +1. APPLICABILITY AND DEFINITIONS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The **Document**, below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as "**you**". You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A "**Modified Version**" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A "**Secondary Section**" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The "**Invariant Sections**" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The "**Cover Texts**" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A "**Transparent**" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not "Transparent" is called **Opaque**. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The "**Title Page**" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +The "**publisher**" means any person or entity that distributes +copies of the Document to the public. + +A section "**Entitled XYZ**" means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as "**Acknowledgements**", +"**Dedications**", "**Endorsements**", or "**History**".) +To "**Preserve the Title**" +of such a section when you modify the Document means that it remains a +section "Entitled XYZ" according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +2. VERBATIM COPYING +~~~~~~~~~~~~~~~~~~~ + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +3. COPYING IN QUANTITY +~~~~~~~~~~~~~~~~~~~~~~ + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +4. MODIFICATIONS +~~~~~~~~~~~~~~~~ + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. + +B. List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement. + +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + +D. Preserve all the copyright notices of the Document. + +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + +F. Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. + +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +H. Include an unaltered copy of this License. + +I. Preserve the section Entitled "History", Preserve its Title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section Entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. + +J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. + +K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section all + the substance and tone of each of the contributor acknowledgements + and/or dedications given therein. + +L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. + +M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + +N. Do not retitle any existing section to be Entitled "Endorsements" + or to conflict in title with any Invariant Section. + +O. Preserve any Warranty Disclaimers. + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +5. COMBINING DOCUMENTS +~~~~~~~~~~~~~~~~~~~~~~ + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled "History" +in the various original documents, forming one section Entitled +"History"; likewise combine any sections Entitled "Acknowledgements", +and any sections Entitled "Dedications". You must delete all sections +Entitled "Endorsements". + +6. COLLECTIONS OF DOCUMENTS +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +7. AGGREGATION WITH INDEPENDENT WORKS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an "aggregate" if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +8. TRANSLATION +~~~~~~~~~~~~~~ + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled "Acknowledgements", +"Dedications", or "History", the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +9. TERMINATION +~~~~~~~~~~~~~~ + +You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. + +10. FUTURE REVISIONS OF THIS LICENSE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +https://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy's public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. + +11. RELICENSING +~~~~~~~~~~~~~~~ + +"Massive Multiauthor Collaboration Site" (or "MMC Site") means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +"Massive Multiauthor Collaboration" (or "MMC") contained in the +site means any set of copyrightable works thus published on the MMC +site. + +"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. + +"Incorporate" means to publish or republish a Document, in whole or +in part, as part of another Document. + +An MMC is "eligible for relicensing" if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. + +The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + + Copyright © YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the "with ... Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. \ No newline at end of file diff --git a/doc/gpl-3.0.rst b/doc/gpl-3.0.rst new file mode 100644 index 00000000000..07ffd72b375 --- /dev/null +++ b/doc/gpl-3.0.rst @@ -0,0 +1,707 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +GNU GENERAL PUBLIC LICENSE +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Version 3, 29 June 2007 + +Copyright (C) 2007 Free Software Foundation, Inc. https://fsf.org/ + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + +Preamble +######## + +The GNU General Public License is a free, copyleft license for software +and other kinds of works. + +The licenses for most software and other practical works are designed to +take away your freedom to share and change the works. By contrast, the +GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + +When we speak of free software, we are referring to freedom, not price. +Our General Public Licenses are designed to make sure that you have the +freedom to distribute copies of free software (and charge for them if +you wish), that you receive source code or can get it if you want it, +that you can change the software or use pieces of it in new free +programs, and that you know you can do these things. + +To protect your rights, we need to prevent others from denying you these +rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + +For example, if you distribute copies of such a program, whether gratis +or for a fee, you must pass on to the recipients the same freedoms that +you received. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + +Developers that use the GNU GPL protect your rights with two steps: (1) +assert copyright on the software, and (2) offer you this License giving +you legal permission to copy, distribute and/or modify it. + +For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + +Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of protecting +users' freedom to change the software. The systematic pattern of such +abuse occurs in the area of products for individuals to use, which is +precisely where it is most unacceptable. Therefore, we have designed +this version of the GPL to prohibit the practice for those products. If +such problems arise substantially in other domains, we stand ready to +extend this provision to those domains in future versions of the GPL, as +needed to protect the freedom of users. + +Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + +The precise terms and conditions for copying, distribution and +modification follow. + +TERMS AND CONDITIONS +#################### + +0. Definitions. +^^^^^^^^^^^^^^^ + +"This License" refers to version 3 of the GNU General Public License. + +"Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + +"The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + +To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + +A "covered work" means either the unmodified Program or a work based on +the Program. + +To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + +To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + +An interactive user interface displays "Appropriate Legal Notices" to +the extent that it includes a convenient and prominently visible feature +that (1) displays an appropriate copyright notice, and (2) tells the +user that there is no warranty for the work (except to the extent that +warranties are provided), that licensees may convey the work under this +License, and how to view a copy of this License. If the interface +presents a list of user commands or options, such as a menu, a prominent +item in the list meets this criterion. + +1. Source Code. +^^^^^^^^^^^^^^^ + +The "source code" for a work means the preferred form of the work for +making modifications to it. "Object code" means any non-source form of a +work. + +A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that is +widely used among developers working in that language. + +The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that Major +Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A "Major +Component", in this context, means a major essential component (kernel, +window system, and so on) of the specific operating system (if any) on +which the executable work runs, or a compiler used to produce the work, +or an object code interpreter used to run it. + +The "Corresponding Source" for a work in object code form means all the +source code needed to generate, install, and (for an executable work) +run the object code and to modify the work, including scripts to control +those activities. However, it does not include the work's System +Libraries, or general-purpose tools or generally available free programs +which are used unmodified in performing those activities but which are +not part of the work. For example, Corresponding Source includes +interface definition files associated with source files for the work, +and the source code for shared libraries and dynamically linked +subprograms that the work is specifically designed to require, such as +by intimate data communication or control flow between those subprograms +and other parts of the work. + +The Corresponding Source need not include anything that users can +regenerate automatically from other parts of the Corresponding Source. + +The Corresponding Source for a work in source code form is that same +work. + +2. Basic Permissions. +^^^^^^^^^^^^^^^^^^^^^ + +All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + +You may make, run and propagate covered works that you do not convey, +without conditions so long as your license otherwise remains in force. +You may convey covered works to others for the sole purpose of having +them make modifications exclusively for you, or provide you with +facilities for running those works, provided that you comply with the +terms of this License in conveying all material for which you do not +control copyright. Those thus making or running the covered works for +you must do so exclusively on your behalf, under your direction and +control, on terms that prohibit them from making any copies of your +copyrighted material outside their relationship with you. + +Conveying under any other circumstances is permitted solely under the +conditions stated below. Sublicensing is not allowed; section 10 makes +it unnecessary. + +3. Protecting Users' Legal Rights From Anti-Circumvention Law. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article 11 +of the WIPO copyright treaty adopted on 20 December 1996, or similar +laws prohibiting or restricting circumvention of such measures. + +When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to the +covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + +4. Conveying Verbatim Copies. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; keep +intact all notices stating that this License and any non-permissive +terms added in accord with section 7 apply to the code; keep intact all +notices of the absence of any warranty; and give all recipients a copy +of this License along with the Program. + +You may charge any price or no price for each copy that you convey, and +you may offer support or warranty protection for a fee. + +5. Conveying Modified Source Versions. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the terms +of section 4, provided that you also meet all of these conditions: + +a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + +b) The work must carry prominent notices stating that it is released + under this License and any conditions added under section 7. This + requirement modifies the requirement in section 4 to "keep intact + all notices". + +c) You must license the entire work, as a whole, under this License + to anyone who comes into possession of a copy. This License will + therefore apply, along with any applicable section 7 additional + terms, to the whole of the work, and all its parts, regardless of + how they are packaged. This License gives no permission to license + the work in any other way, but it does not invalidate such + permission if you have separately received it. + +d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + +A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, and +which are not combined with it such as to form a larger program, in or +on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not used +to limit the access or legal rights of the compilation's users beyond +what the individual works permit. Inclusion of a covered work in an +aggregate does not cause this License to apply to the other parts of the +aggregate. + +6. Conveying Non-Source Forms. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You may convey a covered work in object code form under the terms of +sections 4 and 5, provided that you also convey the machine-readable +Corresponding Source under the terms of this License, in one of these +ways: + +a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + +b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the Corresponding + Source from a network server at no charge. + +c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + +d) Convey the object code by offering access from a designated place + (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + +e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + +A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be included +in conveying the object code work. + +A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for +incorporation into a dwelling. In determining whether a product is a +consumer product, doubtful cases shall be resolved in favor of coverage. +For a particular product received by a particular user, "normally used" +refers to a typical or common use of that class of product, regardless +of the status of the particular user or of the way in which the +particular user actually uses, or expects or is expected to use, the +product. A product is a consumer product regardless of whether the +product has substantial commercial, industrial or non-consumer uses, +unless such uses represent the only significant mode of use of the +product. + +"Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product +from a modified version of its Corresponding Source. The information +must suffice to ensure that the continued functioning of the modified +object code is in no case prevented or interfered with solely because +modification has been made. + +If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied by +the Installation Information. But this requirement does not apply if +neither you nor any third party retains the ability to install modified +object code on the User Product (for example, the work has been +installed in ROM). + +The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + +Corresponding Source conveyed, and Installation Information provided, in +accord with this section must be in a format that is publicly documented +(and with an implementation available to the public in source code +form), and must require no special password or key for unpacking, +reading or copying. + +7. Additional Terms. +^^^^^^^^^^^^^^^^^^^^ + +"Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by this +License without regard to the additional permissions. + +When you convey a copy of a covered work, you may at your option remove +any additional permissions from that copy, or from any part of it. +(Additional permissions may be written to require their own removal in +certain cases when you modify the work.) You may place additional +permissions on material, added by you to a covered work, for which you +have or can give appropriate copyright permission. + +Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders +of that material) supplement the terms of this License with terms: + +a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + +b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + +c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + +d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + +e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + +f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions + of it) with contractual assumptions of liability to the recipient, + for any liability that these contractual assumptions directly + impose on those licensors and authors. + +All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains a +further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms of +that license document, provided that the further restriction does not +survive such relicensing or conveying. + +If you add terms to a covered work in accord with this section, you must +place, in the relevant source files, a statement of the additional terms +that apply to those files, or a notice indicating where to find the +applicable terms. + +Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; the above +requirements apply either way. + +8. Termination. +^^^^^^^^^^^^^^^ + +You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally terminates +your license, and (b) permanently, if the copyright holder fails to +notify you of the violation by some reasonable means prior to 60 days +after the cessation. + +Moreover, your license from a particular copyright holder is reinstated +permanently if the copyright holder notifies you of the violation by +some reasonable means, this is the first time you have received notice +of violation of this License (for any work) from that copyright holder, +and you cure the violation prior to 30 days after your receipt of the +notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + +9. Acceptance Not Required for Having Copies. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You are not required to accept this License in order to receive or run a +copy of the Program. Ancillary propagation of a covered work occurring +solely as a consequence of using peer-to-peer transmission to receive a +copy likewise does not require acceptance. However, nothing other than +this License grants you permission to propagate or modify any covered +work. These actions infringe copyright if you do not accept this +License. Therefore, by modifying or propagating a covered work, you +indicate your acceptance of this License to do so. + +10. Automatic Licensing of Downstream Recipients. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + +An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered work +results from an entity transaction, each party to that transaction who +receives a copy of the work also receives whatever licenses to the work +the party's predecessor in interest had or could give under the previous +paragraph, plus a right to possession of the Corresponding Source of the +work from the predecessor in interest, if the predecessor has it or can +get it with reasonable efforts. + +You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may not +impose a license fee, royalty, or other charge for exercise of rights +granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that any +patent claim is infringed by making, using, selling, offering for sale, +or importing the Program or any portion of it. + +11. Patents. +^^^^^^^^^^^^ + +A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The work +thus licensed is called the contributor's "contributor version". + +A contributor's "essential patent claims" are all patent claims owned or +controlled by the contributor, whether already acquired or hereafter +acquired, that would be infringed by some manner, permitted by this +License, of making, using, or selling its contributor version, but do +not include claims that would be infringed only as a consequence of +further modification of the contributor version. For purposes of this +definition, "control" includes the right to grant patent sublicenses in +a manner consistent with the requirements of this License. + +Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to make, +use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + +In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + +If you convey a covered work, knowingly relying on a patent license, and +the Corresponding Source of the work is not available for anyone to +copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + +If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify or +convey a specific copy of the covered work, then the patent license you +grant is automatically extended to all recipients of the covered work +and works based on it. + +A patent license is "discriminatory" if it does not include within the +scope of its coverage, prohibits the exercise of, or is conditioned on +the non-exercise of one or more of the rights that are specifically +granted under this License. You may not convey a covered work if you are +a party to an arrangement with a third party that is in the business of +distributing software, under which you make payment to the third party +based on the extent of your activity of conveying the work, and under +which the third party grants, to any of the parties who would receive +the covered work from you, a discriminatory patent license (a) in +connection with copies of the covered work conveyed by you (or copies +made from those copies), or (b) primarily for and in connection with +specific products or compilations that contain the covered work, unless +you entered into that arrangement, or that patent license was granted, +prior to 28 March 2007. + +Nothing in this License shall be construed as excluding or limiting any +implied license or other defenses to infringement that may otherwise be +available to you under applicable patent law. + +12. No Surrender of Others' Freedom. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not convey it at all. For example, if you agree to terms that +obligate you to collect a royalty for further conveying from those to +whom you convey the Program, the only way you could satisfy both those +terms and this License would be to refrain entirely from conveying the +Program. + +13. Use with the GNU Affero General Public License. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Notwithstanding any other provision of this License, you have permission +to link or combine any covered work with a work licensed under version 3 +of the GNU Affero General Public License into a single combined work, +and to convey the resulting work. The terms of this License will +continue to apply to the part which is the covered work, but the special +requirements of the GNU Affero General Public License, section 13, +concerning interaction through a network will apply to the combination +as such. + +14. Revised Versions of this License. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Free Software Foundation may publish revised and/or new versions of +the GNU General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies that a certain numbered version of the GNU General Public +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that numbered version or of +any later version published by the Free Software Foundation. If the +Program does not specify a version number of the GNU General Public +License, you may choose any version ever published by the Free Software +Foundation. + +If the Program specifies that a proxy can decide which future versions +of the GNU General Public License can be used, that proxy's public +statement of acceptance of a version permanently authorizes you to +choose that version for the Program. + +Later license versions may give you additional or different permissions. +However, no additional obligations are imposed on any author or +copyright holder as a result of your choosing to follow a later version. + +15. Disclaimer of Warranty. +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT +WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A +PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF +THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME +THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +16. Limitation of Liability. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR +CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES +ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT +NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES +SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE +WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN +ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +17. Interpretation of Sections 15 and 16. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the disclaimer of warranty and limitation of liability provided above +cannot be given local legal effect according to their terms, reviewing +courts shall apply local law that most closely approximates an absolute +waiver of all civil liability in connection with the Program, unless a +warranty or assumption of liability accompanies a copy of the Program in +return for a fee. + +END OF TERMS AND CONDITIONS + +How to Apply These Terms to Your New Programs +############################################# + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + +To do so, attach the following notices to the program. It is safest to +attach them to the start of each source file to most effectively state +the exclusion of warranty; and each file should have at least the +"copyright" line and a pointer to where the full notice is found. + +:: + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + +If the program does terminal interaction, make it output a short notice +like this when it starts in an interactive mode: + +:: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands \`show w' and \`show c' should show the +appropriate parts of the General Public License. Of course, your +program's commands might be different; for a GUI interface, you would +use an "about box". + +You should also get your employer (if you work as a programmer) or +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. For more information on this, and how to apply and follow the +GNU GPL, see https://www.gnu.org/licenses/. + +The GNU General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use the +GNU Lesser General Public License instead of this License. But first, +please read https://www.gnu.org/licenses/why-not-lgpl.html. \ No newline at end of file diff --git a/doc/indices-and-tables.rst b/doc/indices-and-tables.rst new file mode 100644 index 00000000000..92bf73bcb0a --- /dev/null +++ b/doc/indices-and-tables.rst @@ -0,0 +1,13 @@ +.. only:: html + + Indexes and tables + ================== + + :ref:`genindex` + + .. only:: development + + TODO + ---- + + .. todolist:: \ No newline at end of file diff --git a/doc/lgpl-2.1.rst b/doc/lgpl-2.1.rst new file mode 100644 index 00000000000..845de30d8d4 --- /dev/null +++ b/doc/lgpl-2.1.rst @@ -0,0 +1,514 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +GNU LESSER GENERAL PUBLIC LICENSE +--------------------------------- + +.. index:: LGPL, Lesser General Public License + +Version 2.1, February 1999 + +Copyright (C) 1991-2022 Free Software Foundation, Inc. +51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. + +[This is the first released version of the Lesser GPL. It also counts +as the successor of the GNU Library Public License, version 2, hence the +version number 2.1.] + +Preamble +^^^^^^^^ + +The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +Licenses are intended to guarantee your freedom to share and change +free software---to make sure the software is free for all its users. + +This license, the Lesser General Public License, applies to some +specially designated software---typically libraries---of the Free +Software Foundation and other authors who decide to use it. You can use +it too, but we suggest you first think carefully about whether this +license or the ordinary General Public License is the better strategy to +use in any particular case, based on the explanations below. + +When we speak of free software, we are referring to freedom of use, +not price. Our General Public Licenses are designed to make sure that +you have the freedom to distribute copies of free software (and charge +for this service if you wish); that you receive source code or can get +it if you want it; that you can change the software and use pieces of it +in new free programs; and that you are informed that you can do these +things. + +To protect your rights, we need to make restrictions that forbid +distributors to deny you these rights or to ask you to surrender these +rights. These restrictions translate to certain responsibilities for +you if you distribute copies of the library or if you modify it. + +For example, if you distribute copies of the library, whether gratis +or for a fee, you must give the recipients all the rights that we gave +you. You must make sure that they, too, receive or can get the source +code. If you link other code with the library, you must provide +complete object files to the recipients, so that they can relink them +with the library after making changes to the library and recompiling +it. And you must show them these terms so they know their rights. + +We protect your rights with a two-step method: (1) we copyright the +library, and (2) we offer you this license, which gives you legal +permission to copy, distribute and/or modify the library. + +To protect each distributor, we want to make it very clear that +there is no warranty for the free library. Also, if the library is +modified by someone else and passed on, the recipients should know +that what they have is not the original version, so that the original +author's reputation will not be affected by problems that might be +introduced by others. + +Finally, software patents pose a constant threat to the existence of +any free program. We wish to make sure that a company cannot +effectively restrict the users of a free program by obtaining a +restrictive license from a patent holder. Therefore, we insist that +any patent license obtained for a version of the library must be +consistent with the full freedom of use specified in this license. + +Most GNU software, including some libraries, is covered by the +ordinary GNU General Public License. This license, the GNU Lesser +General Public License, applies to certain designated libraries, and +is quite different from the ordinary General Public License. We use +this license for certain libraries in order to permit linking those +libraries into non-free programs. + +When a program is linked with a library, whether statically or using +a shared library, the combination of the two is legally speaking a +combined work, a derivative of the original library. The ordinary +General Public License therefore permits such linking only if the +entire combination fits its criteria of freedom. The Lesser General +Public License permits more lax criteria for linking other code with +the library. + +We call this license the :dfn:`Lesser` General Public License because it +does *Less* to protect the user's freedom than the ordinary General +Public License. It also provides other free software developers Less +of an advantage over competing non-free programs. These disadvantages +are the reason we use the ordinary General Public License for many +libraries. However, the Lesser license provides advantages in certain +special circumstances. + +For example, on rare occasions, there may be a special need to +encourage the widest possible use of a certain library, so that it becomes +a de-facto standard. To achieve this, non-free programs must be +allowed to use the library. A more frequent case is that a free +library does the same job as widely used non-free libraries. In this +case, there is little to gain by limiting the free library to free +software only, so we use the Lesser General Public License. + +In other cases, permission to use a particular library in non-free +programs enables a greater number of people to use a large body of +free software. For example, permission to use the GNU C Library in +non-free programs enables many more people to use the whole GNU +operating system, as well as its variant, the GNU/Linux operating +system. + +Although the Lesser General Public License is Less protective of the +users' freedom, it does ensure that the user of a program that is +linked with the Library has the freedom and the wherewithal to run +that program using a modified version of the Library. + +The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +'work based on the library' and a 'work that uses the library'. The +former contains code derived from the library, whereas the latter must +be combined with the library in order to run. + +#. This License Agreement applies to any software library or other program + which contains a notice placed by the copyright holder or other + authorized party saying it may be distributed under the terms of this + Lesser General Public License (also called 'this License'). Each + licensee is addressed as 'you'. + + A 'library' means a collection of software functions and/or data + prepared so as to be conveniently linked with application programs + (which use some of those functions and data) to form executables. + + The 'Library', below, refers to any such software library or work + which has been distributed under these terms. A 'work based on the + Library' means either the Library or any derivative work under + copyright law: that is to say, a work containing the Library or a + portion of it, either verbatim or with modifications and/or translated + straightforwardly into another language. (Hereinafter, translation is + included without limitation in the term 'modification'.) + + 'Source code' for a work means the preferred form of the work for + making modifications to it. For a library, complete source code means + all the source code for all modules it contains, plus any associated + interface definition files, plus the scripts used to control compilation + and installation of the library. + + Activities other than copying, distribution and modification are not + covered by this License; they are outside its scope. The act of + running a program using the Library is not restricted, and output from + such a program is covered only if its contents constitute a work based + on the Library (independent of the use of the Library in a tool for + writing it). Whether that is true depends on what the Library does + and what the program that uses the Library does. + +#. You may copy and distribute verbatim copies of the Library's + complete source code as you receive it, in any medium, provided that + you conspicuously and appropriately publish on each copy an + appropriate copyright notice and disclaimer of warranty; keep intact + all the notices that refer to this License and to the absence of any + warranty; and distribute a copy of this License along with the + Library. + + You may charge a fee for the physical act of transferring a copy, + and you may at your option offer warranty protection in exchange for a + fee. + +#. You may modify your copy or copies of the Library or any portion + of it, thus forming a work based on the Library, and copy and + distribute such modifications or work under the terms of Section 1 + above, provided that you also meet all of these conditions: + + a* The modified work must itself be a software library. + + * You must cause the files modified to carry prominent notices + stating that you changed the files and the date of any change. + + * You must cause the whole of the work to be licensed at no + charge to all third parties under the terms of this License. + + * If a facility in the modified Library refers to a function or a + table of data to be supplied by an application program that uses + the facility, other than as an argument passed when the facility + is invoked, then you must make a good faith effort to ensure that, + in the event an application does not supply such function or + table, the facility still operates, and performs whatever part of + its purpose remains meaningful. + + (For example, a function in a library to compute square roots has + a purpose that is entirely well-defined independent of the + application. Therefore, Subsection 2d requires that any + application-supplied function or table used by this function must + be optional: if the application does not supply it, the square + root function must still compute square roots.) + + These requirements apply to the modified work as a whole. If + identifiable sections of that work are not derived from the Library, + and can be reasonably considered independent and separate works in + themselves, then this License, and its terms, do not apply to those + sections when you distribute them as separate works. But when you + distribute the same sections as part of a whole which is a work based + on the Library, the distribution of the whole must be on the terms of + this License, whose permissions for other licensees extend to the + entire whole, and thus to each and every part regardless of who wrote + it. + + Thus, it is not the intent of this section to claim rights or contest + your rights to work written entirely by you; rather, the intent is to + exercise the right to control the distribution of derivative or + collective works based on the Library. + + In addition, mere aggregation of another work not based on the Library + with the Library (or with a work based on the Library) on a volume of + a storage or distribution medium does not bring the other work under + the scope of this License. + +#. You may opt to apply the terms of the ordinary GNU General Public + License instead of this License to a given copy of the Library. To do + this, you must alter all the notices that refer to this License, so + that they refer to the ordinary GNU General Public License, version 2, + instead of to this License. (If a newer version than version 2 of the + ordinary GNU General Public License has appeared, then you can specify + that version instead if you wish.) Do not make any other change in + these notices. + + Once this change is made in a given copy, it is irreversible for + that copy, so the ordinary GNU General Public License applies to all + subsequent copies and derivative works made from that copy. + + This option is useful when you wish to copy part of the code of + the Library into a program that is not a library. + +#. You may copy and distribute the Library (or a portion or + derivative of it, under Section 2) in object code or executable form + under the terms of Sections 1 and 2 above provided that you accompany + it with the complete corresponding machine-readable source code, which + must be distributed under the terms of Sections 1 and 2 above on a + medium customarily used for software interchange. + + If distribution of object code is made by offering access to copy + from a designated place, then offering equivalent access to copy the + source code from the same place satisfies the requirement to + distribute the source code, even though third parties are not + compelled to copy the source along with the object code. + +#. A program that contains no derivative of any portion of the + Library, but is designed to work with the Library by being compiled or + linked with it, is called a 'work that uses the Library'. Such a + work, in isolation, is not a derivative work of the Library, and + therefore falls outside the scope of this License. + + However, linking a 'work that uses the Library' with the Library + creates an executable that is a derivative of the Library (because it + contains portions of the Library), rather than a 'work that uses the + library'. The executable is therefore covered by this License. + Section 6 states terms for distribution of such executables. + + When a 'work that uses the Library' uses material from a header file + that is part of the Library, the object code for the work may be a + derivative work of the Library even though the source code is not. + Whether this is true is especially significant if the work can be + linked without the Library, or if the work is itself a library. The + threshold for this to be true is not precisely defined by law. + + If such an object file uses only numerical parameters, data + structure layouts and accessors, and small macros and small inline + functions (ten lines or less in length), then the use of the object + file is unrestricted, regardless of whether it is legally a derivative + work. (Executables containing this object code plus portions of the + Library will still fall under Section 6.) + + Otherwise, if the work is a derivative of the Library, you may + distribute the object code for the work under the terms of Section 6. + Any executables containing that work also fall under Section 6, + whether or not they are linked directly with the Library itself. + +#. As an exception to the Sections above, you may also combine or + link a 'work that uses the Library' with the Library to produce a + work containing portions of the Library, and distribute that work + under terms of your choice, provided that the terms permit + modification of the work for the customer's own use and reverse + engineering for debugging such modifications. + + You must give prominent notice with each copy of the work that the + Library is used in it and that the Library and its use are covered by + this License. You must supply a copy of this License. If the work + during execution displays copyright notices, you must include the + copyright notice for the Library among them, as well as a reference + directing the user to the copy of this License. Also, you must do one + of these things: + + a* Accompany the work with the complete corresponding + machine-readable source code for the Library including whatever + changes were used in the work (which must be distributed under + Sections 1 and 2 above); and, if the work is an executable linked + with the Library, with the complete machine-readable 'work that + uses the Library', as object code and/or source code, so that the + user can modify the Library and then relink to produce a modified + executable containing the modified Library. (It is understood + that the user who changes the contents of definitions files in the + Library will not necessarily be able to recompile the application + to use the modified definitions.) + + * Use a suitable shared library mechanism for linking with the Library. A + suitable mechanism is one that (1) uses at run time a copy of the + library already present on the user's computer system, rather than + copying library functions into the executable, and (2) will operate + properly with a modified version of the library, if the user installs + one, as long as the modified version is interface-compatible with the + version that the work was made with. + + * Accompany the work with a written offer, valid for at + least three years, to give the same user the materials + specified in Subsection 6a, above, for a charge no more + than the cost of performing this distribution. + + * If distribution of the work is made by offering access to copy + from a designated place, offer equivalent access to copy the above + specified materials from the same place. + + * Verify that the user has already received a copy of these + materials or that you have already sent this user a copy. + + For an executable, the required form of the 'work that uses the + Library' must include any data and utility programs needed for + reproducing the executable from it. However, as a special exception, + the materials to be distributed need not include anything that is + normally distributed (in either source or binary form) with the major + components (compiler, kernel, and so on) of the operating system on + which the executable runs, unless that component itself accompanies the + executable. + + It may happen that this requirement contradicts the license + restrictions of other proprietary libraries that do not normally + accompany the operating system. Such a contradiction means you cannot + use both them and the Library together in an executable that you + distribute. + +#. You may place library facilities that are a work based on the + Library side-by-side in a single library together with other library + facilities not covered by this License, and distribute such a combined + library, provided that the separate distribution of the work based on + the Library and of the other library facilities is otherwise + permitted, and provided that you do these two things: + + a* Accompany the combined library with a copy of the same work + based on the Library, uncombined with any other library + facilities. This must be distributed under the terms of the + Sections above. + + * Give prominent notice with the combined library of the fact + that part of it is a work based on the Library, and explaining + where to find the accompanying uncombined form of the same work. + +#. You may not copy, modify, sublicense, link with, or distribute + the Library except as expressly provided under this License. Any + attempt otherwise to copy, modify, sublicense, link with, or + distribute the Library is void, and will automatically terminate your + rights under this License. However, parties who have received copies, + or rights, from you under this License will not have their licenses + terminated so long as such parties remain in full compliance. + +#. You are not required to accept this License, since you have not + signed it. However, nothing else grants you permission to modify or + distribute the Library or its derivative works. These actions are + prohibited by law if you do not accept this License. Therefore, by + modifying or distributing the Library (or any work based on the + Library), you indicate your acceptance of this License to do so, and + all its terms and conditions for copying, distributing or modifying + the Library or works based on it. + +#. Each time you redistribute the Library (or any work based on the + Library), the recipient automatically receives a license from the + original licensor to copy, distribute, link with or modify the Library + subject to these terms and conditions. You may not impose any further + restrictions on the recipients' exercise of the rights granted herein. + You are not responsible for enforcing compliance by third parties with + this License. + +#. If, as a consequence of a court judgment or allegation of patent + infringement or for any other reason (not limited to patent issues), + conditions are imposed on you (whether by court order, agreement or + otherwise) that contradict the conditions of this License, they do not + excuse you from the conditions of this License. If you cannot + distribute so as to satisfy simultaneously your obligations under this + License and any other pertinent obligations, then as a consequence you + may not distribute the Library at all. For example, if a patent + license would not permit royalty-free redistribution of the Library by + all those who receive copies directly or indirectly through you, then + the only way you could satisfy both it and this License would be to + refrain entirely from distribution of the Library. + + If any portion of this section is held invalid or unenforceable under any + particular circumstance, the balance of the section is intended to apply, + and the section as a whole is intended to apply in other circumstances. + + It is not the purpose of this section to induce you to infringe any + patents or other property right claims or to contest validity of any + such claims; this section has the sole purpose of protecting the + integrity of the free software distribution system which is + implemented by public license practices. Many people have made + generous contributions to the wide range of software distributed + through that system in reliance on consistent application of that + system; it is up to the author/donor to decide if he or she is willing + to distribute software through any other system and a licensee cannot + impose that choice. + + This section is intended to make thoroughly clear what is believed to + be a consequence of the rest of this License. + +#. If the distribution and/or use of the Library is restricted in + certain countries either by patents or by copyrighted interfaces, the + original copyright holder who places the Library under this License may add + an explicit geographical distribution limitation excluding those countries, + so that distribution is permitted only in or among countries not thus + excluded. In such case, this License incorporates the limitation as if + written in the body of this License. + +#. The Free Software Foundation may publish revised and/or new + versions of the Lesser General Public License from time to time. + Such new versions will be similar in spirit to the present version, + but may differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the Library + specifies a version number of this License which applies to it and + 'any later version', you have the option of following the terms and + conditions either of that version or of any later version published by + the Free Software Foundation. If the Library does not specify a + license version number, you may choose any version ever published by + the Free Software Foundation. + +#. If you wish to incorporate parts of the Library into other free + programs whose distribution conditions are incompatible with these, + write to the author to ask for permission. For software which is + copyrighted by the Free Software Foundation, write to the Free + Software Foundation; we sometimes make exceptions for this. Our + decision will be guided by the two goals of preserving the free status + of all derivatives of our free software and of promoting the sharing + and reuse of software generally. + + NO WARRANTY + +#. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO + WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. + EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR + OTHER PARTIES PROVIDE THE LIBRARY 'AS IS' WITHOUT WARRANTY OF ANY + KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE + LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME + THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +#. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY + AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU + FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR + CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE + LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING + RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A + FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF + SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH + DAMAGES. + +How to Apply These Terms to Your New Libraries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you develop a new library, and you want it to be of the greatest +possible use to the public, we recommend making it free software that +everyone can redistribute and change. You can do so by permitting +redistribution under these terms (or, alternatively, under the terms of the +ordinary General Public License). + +To apply these terms, attach the following notices to the library. It is +safest to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least the +'copyright' line and a pointer to where the full notice is found. + +.. code-block:: + + one line to give the library's name and an idea of what it does. + Copyright (C) year name of author + + This library is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or (at + your option) any later version. + + This library is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA. + +Also add information on how to contact you by electronic and paper mail. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a 'copyright disclaimer' for the library, if +necessary. Here is a sample; alter the names: + +.. code-block:: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the library + `Frob' (a library for tweaking knobs) written by James Random Hacker. + + signature of Ty Coon, 1 April 1990 + Ty Coon, President of Vice + +That's all there is to it! \ No newline at end of file diff --git a/doc/logo.pdf b/doc/logo.pdf new file mode 100644 index 00000000000..4ba78b166b4 Binary files /dev/null and b/doc/logo.pdf differ diff --git a/doc/logo.svg b/doc/logo.svg new file mode 100644 index 00000000000..0b8ed020c89 --- /dev/null +++ b/doc/logo.svg @@ -0,0 +1,108 @@ + + + + + + + + + + + + + + + + + + + diff --git a/doc/md.rst b/doc/md.rst new file mode 100644 index 00000000000..55e0711113e --- /dev/null +++ b/doc/md.rst @@ -0,0 +1,3142 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: simple constraints + +.. _simple-constraints: + +Simple Constraints +^^^^^^^^^^^^^^^^^^ + +The simplest kind of constraint is a string full of letters, each of +which describes one kind of operand that is permitted. Here are +the letters that are allowed: + +whitespace + Whitespace characters are ignored and can be inserted at any position + except the first. This enables each alternative for different operands to + be visually aligned in the machine description even if they have different + number of constraints and modifiers. + + .. index:: m in constraint, memory references in constraints + +m + A memory operand is allowed, with any kind of address that the machine + supports in general. + Note that the letter used for the general memory constraint can be + re-defined by a back end using the ``TARGET_MEM_CONSTRAINT`` macro. + + .. index:: offsettable address, o in constraint + +o + A memory operand is allowed, but only if the address is + :dfn:`offsettable`. This means that adding a small integer (actually, + the width in bytes of the operand, as determined by its machine mode) + may be added to the address and the result is also a valid memory + address. + + .. index:: autoincrement/decrement addressing + + For example, an address which is constant is offsettable; so is an + address that is the sum of a register and a constant (as long as a + slightly larger constant is also within the range of address-offsets + supported by the machine); but an autoincrement or autodecrement + address is not offsettable. More complicated indirect/indexed + addresses may or may not be offsettable depending on the other + addressing modes that the machine supports. + + Note that in an output operand which can be matched by another + operand, the constraint letter :samp:`o` is valid only when accompanied + by both :samp:`<` (if the target machine has predecrement addressing) + and :samp:`>` (if the target machine has preincrement addressing). + + .. index:: V in constraint + +V + A memory operand that is not offsettable. In other words, anything that + would fit the :samp:`m` constraint but not the :samp:`o` constraint. + + .. index:: < in constraint + +< + A memory operand with autodecrement addressing (either predecrement or + postdecrement) is allowed. In inline ``asm`` this constraint is only + allowed if the operand is used exactly once in an instruction that can + handle the side effects. Not using an operand with :samp:`<` in constraint + string in the inline ``asm`` pattern at all or using it in multiple + instructions isn't valid, because the side effects wouldn't be performed + or would be performed more than once. Furthermore, on some targets + the operand with :samp:`<` in constraint string must be accompanied by + special instruction suffixes like ``%U0`` instruction suffix on PowerPC + or ``%P0`` on IA-64. + + .. index:: > in constraint + +> + A memory operand with autoincrement addressing (either preincrement or + postincrement) is allowed. In inline ``asm`` the same restrictions + as for :samp:`<` apply. + + .. index:: r in constraint, registers in constraints + +r + A register operand is allowed provided that it is in a general + register. + + .. index:: constants in constraints, i in constraint + +i + An immediate integer operand (one with constant value) is allowed. + This includes symbolic constants whose values will be known only at + assembly time or later. + + .. index:: n in constraint + +n + An immediate integer operand with a known numeric value is allowed. + Many systems cannot support assembly-time constants for operands less + than a word wide. Constraints for these operands should use :samp:`n` + rather than :samp:`i`. + + .. index:: I in constraint + +:samp:`{I}, {J}, {K}, ... {P}` + Other letters in the range :samp:`I` through :samp:`P` may be defined in + a machine-dependent fashion to permit immediate integer operands with + explicit integer values in specified ranges. For example, on the + 68000, :samp:`I` is defined to stand for the range of values 1 to 8. + This is the range permitted as a shift count in the shift + instructions. + + .. index:: E in constraint + +E + An immediate floating operand (expression code ``const_double``) is + allowed, but only if the target floating point format is the same as + that of the host machine (on which the compiler is running). + + .. index:: F in constraint + +F + An immediate floating operand (expression code ``const_double`` or + ``const_vector``) is allowed. + + .. index:: G in constraint, H in constraint + +:samp:`{G}, {H}` + :samp:`G` and :samp:`H` may be defined in a machine-dependent fashion to + permit immediate floating operands in particular ranges of values. + + .. index:: s in constraint + +s + An immediate integer operand whose value is not an explicit integer is + allowed. + + This might appear strange; if an insn allows a constant operand with a + value not known at compile time, it certainly must allow any known + value. So why use :samp:`s` instead of :samp:`i`? Sometimes it allows + better code to be generated. + + For example, on the 68000 in a fullword instruction it is possible to + use an immediate operand; but if the immediate value is between -128 + and 127, better code results from loading the value into a register and + using the register. This is because the load into the register can be + done with a :samp:`moveq` instruction. We arrange for this to happen + by defining the letter :samp:`K` to mean 'any integer outside the + range -128 to 127', and then specifying :samp:`Ks` in the operand + constraints. + + .. index:: g in constraint + +g + Any register, memory or immediate integer operand is allowed, except for + registers that are not general registers. + + .. index:: X in constraint + +X + + .. only:: gccint + + Any operand whatsoever is allowed, even if it does not satisfy + ``general_operand``. This is normally used in the constraint of + a ``match_scratch`` when certain alternatives will not actually + require a scratch register. + + .. only:: not gccint + + Any operand whatsoever is allowed. + + .. index:: 0 in constraint, digits in constraint + +:samp:`{0}, {1}, {2}, ... {9}` + An operand that matches the specified operand number is allowed. If a + digit is used together with letters within the same alternative, the + digit should come last. + + This number is allowed to be more than a single digit. If multiple + digits are encountered consecutively, they are interpreted as a single + decimal integer. There is scant chance for ambiguity, since to-date + it has never been desirable that :samp:`10` be interpreted as matching + either operand 1 *or* operand 0. Should this be desired, one + can use multiple alternatives instead. + + .. index:: matching constraint, constraint, matching + + This is called a :dfn:`matching constraint` and what it really means is + that the assembler has only a single operand that fills two roles + + .. only:: gccint + + considered separate in the RTL insn. For example, an add insn has two + input operands and one output operand in the RTL, but on most CISC + + .. only:: not gccint + + which ``asm`` distinguishes. For example, an add instruction uses + two input operands and an output operand, but on most CISC + + machines an add instruction really has only two operands, one of them an + input-output operand: + + .. code-block:: + + addl #35,r12 + + Matching constraints are used in these circumstances. + More precisely, the two operands that match must include one input-only + operand and one output-only operand. Moreover, the digit must be a + smaller number than the number of the operand that uses it in the + constraint. + + .. only:: gccint + + For operands to match in a particular case usually means that they + are identical-looking RTL expressions. But in a few special cases + specific kinds of dissimilarity are allowed. For example, ``*x`` + as an input operand will match ``*x++`` as an output operand. + For proper results in such cases, the output template should always + use the output-operand's number when printing the operand. + + .. index:: load address instruction, push address instruction, address constraints, p in constraint + +p + An operand that is a valid memory address is allowed. This is + for 'load address' and 'push address' instructions. + + .. index:: address_operand + + :samp:`p` in the constraint must be accompanied by ``address_operand`` + as the predicate in the ``match_operand``. This predicate interprets + the mode specified in the ``match_operand`` as the mode of the memory + reference for which the address would be valid. + + .. index:: other register constraints, extensible constraints + +other-letters + Other letters can be defined in machine-dependent fashion to stand for + particular classes of registers or other arbitrary operand types. + :samp:`d`, :samp:`a` and :samp:`f` are defined on the 68000/68020 to stand + for data, address and floating point registers. + +.. only:: gccint + + In order to have valid assembler code, each operand must satisfy + its constraint. But a failure to do so does not prevent the pattern + from applying to an insn. Instead, it directs the compiler to modify + the code so that the constraint will be satisfied. Usually this is + done by copying an operand into a register. + + Contrast, therefore, the two instruction patterns that follow: + + .. code-block:: c++ + + (define_insn "" + [(set (match_operand:SI 0 "general_operand" "=r") + (plus:SI (match_dup 0) + (match_operand:SI 1 "general_operand" "r")))] + "" + "...") + + which has two operands, one of which must appear in two places, and + + .. code-block:: c++ + + (define_insn "" + [(set (match_operand:SI 0 "general_operand" "=r") + (plus:SI (match_operand:SI 1 "general_operand" "0") + (match_operand:SI 2 "general_operand" "r")))] + "" + "...") + + which has three operands, two of which are required by a constraint to be + identical. If we are considering an insn of the form + + .. code-block:: c++ + + (insn n prev next + (set (reg:SI 3) + (plus:SI (reg:SI 6) (reg:SI 109))) + ...) + + the first pattern would not apply at all, because this insn does not + contain two identical subexpressions in the right place. The pattern would + say, 'That does not look like an add instruction; try other patterns'. + The second pattern would say, 'Yes, that's an add instruction, but there + is something wrong with it'. It would direct the reload pass of the + compiler to generate additional insns to make the constraint true. The + results might look like this: + + .. code-block:: c++ + + (insn n2 prev n + (set (reg:SI 3) (reg:SI 6)) + ...) + + (insn n n2 next + (set (reg:SI 3) + (plus:SI (reg:SI 3) (reg:SI 109))) + ...) + + It is up to you to make sure that each operand, in each pattern, has + constraints that can handle any RTL expression that could be present for + that operand. (When multiple alternatives are in use, each pattern must, + for each possible combination of operand expressions, have at least one + alternative which can handle that combination of operands.) The + constraints don't need to *allow* any possible operand---when this is + the case, they do not constrain---but they must at least point the way to + reloading any possible operand so that it will fit. + + * If the constraint accepts whatever operands the predicate permits, + there is no problem: reloading is never necessary for this operand. + + For example, an operand whose constraints permit everything except + registers is safe provided its predicate rejects registers. + + An operand whose predicate accepts only constant values is safe + provided its constraints include the letter :samp:`i`. If any possible + constant value is accepted, then nothing less than :samp:`i` will do; + if the predicate is more selective, then the constraints may also be + more selective. + + * Any operand expression can be reloaded by copying it into a register. + So if an operand's constraints allow some kind of register, it is + certain to be safe. It need not permit all classes of registers; the + compiler knows how to copy a register into another register of the + proper class in order to make an instruction valid. + + .. index:: nonoffsettable memory reference, memory reference, nonoffsettable + + * A nonoffsettable memory reference can be reloaded by copying the + address into a register. So if the constraint uses the letter + :samp:`o`, all memory references are taken care of. + + * A constant operand can be reloaded by allocating space in memory to + hold it as preinitialized data. Then the memory reference can be used + in place of the constant. So if the constraint uses the letters + :samp:`o` or :samp:`m`, constant operands are not a problem. + + * If the constraint permits a constant and a pseudo register used in an insn + was not allocated to a hard register and is equivalent to a constant, + the register will be replaced with the constant. If the predicate does + not permit a constant and the insn is re-recognized for some reason, the + compiler will crash. Thus the predicate must always recognize any + objects allowed by the constraint. + + If the operand's predicate can recognize registers, but the constraint does + not permit them, it can make the compiler crash. When this operand happens + to be a register, the reload pass will be stymied, because it does not know + how to copy a register temporarily into memory. + + If the predicate accepts a unary operator, the constraint applies to the + operand. For example, the MIPS processor at ISA level 3 supports an + instruction which adds two registers in ``SImode`` to produce a + ``DImode`` result, but only if the registers are correctly sign + extended. This predicate for the input operands accepts a + ``sign_extend`` of an ``SImode`` register. Write the constraint + to indicate the type of register that is required for the operand of the + ``sign_extend``. + +.. only:: not gccint + + So the first alternative for the 68000's logical-or could be written as + ``"+m" (output) : "ir" (input)``. The second could be ``"+r" + (output): "irm" (input)``. However, the fact that two memory locations + cannot be used in a single instruction prevents simply using ``"+rm" + (output) : "irm" (input)``. Using multi-alternatives, this might be + written as ``"+m,r" (output) : "ir,irm" (input)``. This describes + all the available alternatives to the compiler, allowing it to choose + the most efficient one for the current conditions. + + There is no way within the template to determine which alternative was + chosen. However you may be able to wrap your ``asm`` statements with + builtins such as ``__builtin_constant_p`` to achieve the desired results. + +.. index:: multiple alternative constraints + +.. _multi-alternative: + +Multiple Alternative Constraints +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sometimes a single instruction has multiple alternative sets of possible +operands. For example, on the 68000, a logical-or instruction can combine +register or an immediate value into memory, or it can combine any kind of +operand into a register; but it cannot combine one memory location into +another. + +These constraints are represented as multiple alternatives. An alternative +can be described by a series of letters for each operand. The overall +constraint for an operand is made from the letters for this operand +from the first alternative, a comma, the letters for this operand from +the second alternative, a comma, and so on until the last alternative. +All operands for a single instruction must have the same number of +alternatives. + +.. only:: gccint + + Here is how it is done for fullword logical-or on the 68000: + + .. code-block:: c++ + + (define_insn "iorsi3" + [(set (match_operand:SI 0 "general_operand" "=m,d") + (ior:SI (match_operand:SI 1 "general_operand" "%0,0") + (match_operand:SI 2 "general_operand" "dKs,dmKs")))] + ...) + + The first alternative has :samp:`m` (memory) for operand 0, :samp:`0` for + operand 1 (meaning it must match operand 0), and :samp:`dKs` for operand + 2. The second alternative has :samp:`d` (data register) for operand 0, + :samp:`0` for operand 1, and :samp:`dmKs` for operand 2. The :samp:`=` and + :samp:`%` in the constraints apply to all the alternatives; their + meaning is explained in the next section (see :ref:`class-preferences`). + + If all the operands fit any one alternative, the instruction is valid. + Otherwise, for each alternative, the compiler counts how many instructions + must be added to copy the operands so that that alternative applies. + The alternative requiring the least copying is chosen. If two alternatives + need the same amount of copying, the one that comes first is chosen. + These choices can be altered with the :samp:`?` and :samp:`!` characters: + + .. index:: ? in constraint, question mark + + ``?`` + Disparage slightly the alternative that the :samp:`?` appears in, + as a choice when no alternative applies exactly. The compiler regards + this alternative as one unit more costly for each :samp:`?` that appears + in it. + + .. index:: ! in constraint, exclamation point + + ``!`` + Disparage severely the alternative that the :samp:`!` appears in. + This alternative can still be used if it fits without reloading, + but if reloading is needed, some other alternative will be used. + + .. index:: ^ in constraint, caret + + ``^`` + This constraint is analogous to :samp:`?` but it disparages slightly + the alternative only if the operand with the :samp:`^` needs a reload. + + .. index:: $ in constraint, dollar sign + + ``$`` + This constraint is analogous to :samp:`!` but it disparages severely + the alternative only if the operand with the :samp:`$` needs a reload. + + When an insn pattern has multiple alternatives in its constraints, often + the appearance of the assembler code is determined mostly by which + alternative was matched. When this is so, the C code for writing the + assembler code can use the variable ``which_alternative``, which is + the ordinal number of the alternative that was actually satisfied (0 for + the first, 1 for the second alternative, etc.). See :ref:`output-statement`. + +.. _class-preferences: + +Register Class Preferences +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. only:: gccint + + .. index:: class preference constraints, register class preference constraints, voting between constraint alternatives + + The operand constraints have another function: they enable the compiler + to decide which kind of hardware register a pseudo register is best + allocated to. The compiler examines the constraints that apply to the + insns that use the pseudo register, looking for the machine-dependent + letters such as :samp:`d` and :samp:`a` that specify classes of registers. + The pseudo register is put in whichever class gets the most 'votes'. + The constraint letters :samp:`g` and :samp:`r` also vote: they vote in + favor of a general register. The machine description says which registers + are considered general. + + Of course, on some machines all registers are equivalent, and no register + classes are defined. Then none of this complexity is relevant. + +.. index:: modifiers in constraints, constraint modifier characters + +.. _modifiers: + +Constraint Modifier Characters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. prevent bad page break with this line + +Here are constraint modifier characters. + +.. index:: = in constraint + +:samp:`=` + Means that this operand is written to by this instruction: + the previous value is discarded and replaced by new data. + + .. index:: + in constraint + +:samp:`+` + Means that this operand is both read and written by the instruction. + + When the compiler fixes up the operands to satisfy the constraints, + it needs to know which operands are read by the instruction and + which are written by it. :samp:`=` identifies an operand which is only + written; :samp:`+` identifies an operand that is both read and written; all + other operands are assumed to only be read. + + If you specify :samp:`=` or :samp:`+` in a constraint, you put it in the + first character of the constraint string. + + .. index:: & in constraint, earlyclobber operand + +:samp:`&` + Means (in a particular alternative) that this operand is an + :dfn:`earlyclobber` operand, which is written before the instruction is + finished using the input operands. Therefore, this operand may not lie + in a register that is read by the instruction or as part of any memory + address. + + :samp:`&` applies only to the alternative in which it is written. In + constraints with multiple alternatives, sometimes one alternative + requires :samp:`&` while others do not. See, for example, the + :samp:`movdf` insn of the 68000. + + An operand which is read by the instruction can be tied to an earlyclobber + operand if its only use as an input occurs before the early result is + written. Adding alternatives of this form often allows GCC to produce + better code when only some of the read operands can be affected by the + earlyclobber. See, for example, the :samp:`mulsi3` insn of the ARM. + + Furthermore, if the :dfn:`earlyclobber` operand is also a read/write + operand, then that operand is written only after it's used. + + :samp:`&` does not obviate the need to write :samp:`=` or :samp:`+`. As + :dfn:`earlyclobber` operands are always written, a read-only + :dfn:`earlyclobber` operand is ill-formed and will be rejected by the + compiler. + + .. index:: % in constraint + +:samp:`%` + Declares the instruction to be commutative for this operand and the + following operand. This means that the compiler may interchange the + two operands if that is the cheapest way to make all operands fit the + constraints. :samp:`%` applies to all alternatives and must appear as + the first character in the constraint. Only read-only operands can use + :samp:`%`. + + .. only:: gccint + + This is often used in patterns for addition instructions + that really have only two operands: the result must go in one of the + arguments. Here for example, is how the 68000 halfword-add + instruction is defined: + + .. code-block:: c++ + + (define_insn "addhi3" + [(set (match_operand:HI 0 "general_operand" "=m,r") + (plus:HI (match_operand:HI 1 "general_operand" "%0,0") + (match_operand:HI 2 "general_operand" "di,g")))] + ...) + + GCC can only handle one commutative pair in an asm; if you use more, + the compiler may fail. Note that you need not use the modifier if + the two alternatives are strictly identical; this would only waste + time in the reload pass. + + .. only:: gccint + + The modifier is not operational after + register allocation, so the result of ``define_peephole2`` + and ``define_split`` s performed after reload cannot rely on + :samp:`%` to make the intended insn match. + + .. index:: # in constraint + + :samp:`#` + Says that all following characters, up to the next comma, are to be + ignored as a constraint. They are significant only for choosing + register preferences. + + .. index:: * in constraint + + :samp:`*` + Says that the following character should be ignored when choosing + register preferences. :samp:`*` has no effect on the meaning of the + constraint as a constraint, and no effect on reloading. For LRA + :samp:`*` additionally disparages slightly the alternative if the + following character matches the operand. + + Here is an example: the 68000 has an instruction to sign-extend a + halfword in a data register, and can also sign-extend a value by + copying it into an address register. While either kind of register is + acceptable, the constraints on an address-register destination are + less strict, so it is best if register allocation makes an address + register its goal. Therefore, :samp:`*` is used so that the :samp:`d` + constraint letter (for data register) is ignored when computing + register preferences. + + .. code-block:: c++ + + (define_insn "extendhisi2" + [(set (match_operand:SI 0 "general_operand" "=*d,a") + (sign_extend:SI + (match_operand:HI 1 "general_operand" "0,g")))] + ...) + +.. index:: machine specific constraints, constraints, machine specific + +.. _machine-constraints: + +Constraints for Particular Machines +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Whenever possible, you should use the general-purpose constraint letters +in ``asm`` arguments, since they will convey meaning more readily to +people reading your code. Failing that, use the constraint letters +that usually have very similar meanings across architectures. The most +commonly used constraints are :samp:`m` and :samp:`r` (for memory and +general-purpose registers respectively; see :ref:`simple-constraints`), and +:samp:`I`, usually the letter indicating the most common +immediate-constant format. + +Each architecture defines additional constraints. These constraints +are used by the compiler itself for instruction generation, as well as +for ``asm`` statements; therefore, some of the constraints are not +particularly useful for ``asm``. Here is a summary of some of the +machine-dependent constraints available on some particular machines; +it includes both constraints that are useful for ``asm`` and +constraints that aren't. The compiler source file mentioned in the +table heading for each architecture is the definitive reference for +the meanings of that architecture's constraints. + +.. Please keep this table alphabetized by target! + +AArch64 family---:samp:`{config/aarch64/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``k`` + The stack pointer register (``SP``) + +``w`` + Floating point register, Advanced SIMD vector register or SVE vector register + +``x`` + Like ``w``, but restricted to registers 0 to 15 inclusive. + +``y`` + Like ``w``, but restricted to registers 0 to 7 inclusive. + +``Upl`` + One of the low eight SVE predicate registers (``P0`` to ``P7``) + +``Upa`` + Any of the SVE predicate registers (``P0`` to ``P15``) + +``I`` + Integer constant that is valid as an immediate operand in an ``ADD`` + instruction + +``J`` + Integer constant that is valid as an immediate operand in a ``SUB`` + instruction (once negated) + +``K`` + Integer constant that can be used with a 32-bit logical instruction + +``L`` + Integer constant that can be used with a 64-bit logical instruction + +``M`` + Integer constant that is valid as an immediate operand in a 32-bit ``MOV`` + pseudo instruction. The ``MOV`` may be assembled to one of several different + machine instructions depending on the value + +``N`` + Integer constant that is valid as an immediate operand in a 64-bit ``MOV`` + pseudo instruction + +``S`` + An absolute symbolic address or a label reference + +``Y`` + Floating point constant zero + +``Z`` + Integer constant zero + +``Ush`` + The high part (bits 12 and upwards) of the pc-relative address of a symbol + within 4GB of the instruction + +``Q`` + A memory address which uses a single base register with no offset + +``Ump`` + A memory address suitable for a load/store pair instruction in SI, DI, SF and + DF modes + +AMD GCN ---:samp:`{config/gcn/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``I`` + Immediate integer in the range -16 to 64 + +``J`` + Immediate 16-bit signed integer + +``Kf`` + Immediate constant -1 + +``L`` + Immediate 15-bit unsigned integer + +``A`` + Immediate constant that can be inlined in an instruction encoding: integer + -16..64, or float 0.0, +/-0.5, +/-1.0, +/-2.0, + +/-4.0, 1.0/(2.0\*PI) + +``B`` + Immediate 32-bit signed integer that can be attached to an instruction encoding + +``C`` + Immediate 32-bit integer in range -16..4294967295 (i.e. 32-bit unsigned + integer or :samp:`A` constraint) + +``DA`` + Immediate 64-bit constant that can be split into two :samp:`A` constants + +``DB`` + Immediate 64-bit constant that can be split into two :samp:`B` constants + +``U`` + Any ``unspec`` + +``Y`` + Any ``symbol_ref`` or ``label_ref`` + +``v`` + VGPR register + +``Sg`` + SGPR register + +``SD`` + SGPR registers valid for instruction destinations, including VCC, M0 and EXEC + +``SS`` + SGPR registers valid for instruction sources, including VCC, M0, EXEC and SCC + +``Sm`` + SGPR registers valid as a source for scalar memory instructions (excludes M0 + and EXEC) + +``Sv`` + SGPR registers valid as a source or destination for vector instructions + (excludes EXEC) + +``ca`` + All condition registers: SCC, VCCZ, EXECZ + +``cs`` + Scalar condition register: SCC + +``cV`` + Vector condition register: VCC, VCC_LO, VCC_HI + +``e`` + EXEC register (EXEC_LO and EXEC_HI) + +``RB`` + Memory operand with address space suitable for ``buffer_*`` instructions + +``RF`` + Memory operand with address space suitable for ``flat_*`` instructions + +``RS`` + Memory operand with address space suitable for ``s_*`` instructions + +``RL`` + Memory operand with address space suitable for ``ds_*`` LDS instructions + +``RG`` + Memory operand with address space suitable for ``ds_*`` GDS instructions + +``RD`` + Memory operand with address space suitable for any ``ds_*`` instructions + +``RM`` + Memory operand with address space suitable for ``global_*`` instructions + +ARC ---:samp:`{config/arc/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``q`` + Registers usable in ARCompact 16-bit instructions: ``r0`` - ``r3``, + ``r12`` - ``r15``. This constraint can only match when the :option:`-mq` + option is in effect. + +``e`` + Registers usable as base-regs of memory addresses in ARCompact 16-bit memory + instructions: ``r0`` - ``r3``, ``r12`` - ``r15``, ``sp``. + This constraint can only match when the :option:`-mq` + option is in effect. + +``D`` + ARC FPX (dpfp) 64-bit registers. ``D0``, ``D1``. + +``I`` + A signed 12-bit integer constant. + +``Cal`` + constant for arithmetic/logical operations. This might be any constant + that can be put into a long immediate by the assmbler or linker without + involving a PIC relocation. + +``K`` + A 3-bit unsigned integer constant. + +``L`` + A 6-bit unsigned integer constant. + +``CnL`` + One's complement of a 6-bit unsigned integer constant. + +``CmL`` + Two's complement of a 6-bit unsigned integer constant. + +``M`` + A 5-bit unsigned integer constant. + +``O`` + A 7-bit unsigned integer constant. + +``P`` + A 8-bit unsigned integer constant. + +``H`` + Any const_double value. + +ARM family---:samp:`{config/arm/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``h`` + In Thumb state, the core registers ``r8`` - ``r15``. + +``k`` + The stack pointer register. + +``l`` + In Thumb State the core registers ``r0`` - ``r7``. In ARM state this + is an alias for the ``r`` constraint. + +``t`` + VFP floating-point registers ``s0`` - ``s31``. Used for 32 bit values. + +``w`` + VFP floating-point registers ``d0`` - ``d31`` and the appropriate + subset ``d0`` - ``d15`` based on command line options. + Used for 64 bit values only. Not valid for Thumb1. + +``y`` + The iWMMX co-processor registers. + +``z`` + The iWMMX GR registers. + +``G`` + The floating-point constant 0.0 + +``I`` + Integer that is valid as an immediate operand in a data processing + instruction. That is, an integer in the range 0 to 255 rotated by a + multiple of 2 + +``J`` + Integer in the range -4095 to 4095 + +``K`` + Integer that satisfies constraint :samp:`I` when inverted (ones complement) + +``L`` + Integer that satisfies constraint :samp:`I` when negated (twos complement) + +``M`` + Integer in the range 0 to 32 + +``Q`` + A memory reference where the exact address is in a single register + (':samp:`m`' is preferable for ``asm`` statements) + +``R`` + An item in the constant pool + +``S`` + A symbol in the text segment of the current file + +``Uv`` + A memory reference suitable for VFP load/store insns (reg+constant offset) + +``Uy`` + A memory reference suitable for iWMMXt load/store instructions. + +``Uq`` + A memory reference suitable for the ARMv4 ldrsb instruction. + +AVR family---:samp:`{config/avr/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``l`` + Registers from r0 to r15 + +``a`` + Registers from r16 to r23 + +``d`` + Registers from r16 to r31 + +``w`` + Registers from r24 to r31. These registers can be used in :samp:`adiw` command + +``e`` + Pointer register (r26--r31) + +``b`` + Base pointer register (r28--r31) + +``q`` + Stack pointer register (SPH:SPL) + +``t`` + Temporary register r0 + +``x`` + Register pair X (r27:r26) + +``y`` + Register pair Y (r29:r28) + +``z`` + Register pair Z (r31:r30) + +``I`` + Constant greater than -1, less than 64 + +``J`` + Constant greater than -64, less than 1 + +``K`` + Constant integer 2 + +``L`` + Constant integer 0 + +``M`` + Constant that fits in 8 bits + +``N`` + Constant integer -1 + +``O`` + Constant integer 8, 16, or 24 + +``P`` + Constant integer 1 + +``G`` + A floating point constant 0.0 + +``Q`` + A memory address based on Y or Z pointer with displacement. + +Blackfin family---:samp:`{config/bfin/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``a`` + P register + +``d`` + D register + +``z`` + A call clobbered P register. + +:samp:`q{n}` + A single register. If :samp:`{n}` is in the range 0 to 7, the corresponding D + register. If it is ``A``, then the register P0. + +``D`` + Even-numbered D register + +``W`` + Odd-numbered D register + +``e`` + Accumulator register. + +``A`` + Even-numbered accumulator register. + +``B`` + Odd-numbered accumulator register. + +``b`` + I register + +``v`` + B register + +``f`` + M register + +``c`` + Registers used for circular buffering, i.e. I, B, or L registers. + +``C`` + The CC register. + +``t`` + LT0 or LT1. + +``k`` + LC0 or LC1. + +``u`` + LB0 or LB1. + +``x`` + Any D, P, B, M, I or L register. + +``y`` + Additional registers typically used only in prologues and epilogues: RETS, + RETN, RETI, RETX, RETE, ASTAT, SEQSTAT and USP. + +``w`` + Any register except accumulators or CC. + +``Ksh`` + Signed 16 bit integer (in the range -32768 to 32767) + +``Kuh`` + Unsigned 16 bit integer (in the range 0 to 65535) + +``Ks7`` + Signed 7 bit integer (in the range -64 to 63) + +``Ku7`` + Unsigned 7 bit integer (in the range 0 to 127) + +``Ku5`` + Unsigned 5 bit integer (in the range 0 to 31) + +``Ks4`` + Signed 4 bit integer (in the range -8 to 7) + +``Ks3`` + Signed 3 bit integer (in the range -3 to 4) + +``Ku3`` + Unsigned 3 bit integer (in the range 0 to 7) + +:samp:`P{n}` + Constant :samp:`{n}`, where :samp:`{n}` is a single-digit constant in the range 0 to 4. + +``PA`` + An integer equal to one of the MACFLAG_XXX constants that is suitable for + use with either accumulator. + +``PB`` + An integer equal to one of the MACFLAG_XXX constants that is suitable for + use only with accumulator A1. + +``M1`` + Constant 255. + +``M2`` + Constant 65535. + +``J`` + An integer constant with exactly a single bit set. + +``L`` + An integer constant with all bits set except exactly one. + +``H``, ``Q`` + + Any SYMBOL_REF. + +C-SKY---:samp:`{config/csky/constraints.md}` + +``a`` + The mini registers r0 - r7. + +``b`` + The low registers r0 - r15. + +``c`` + C register. + +``y`` + HI and LO registers. + +``l`` + LO register. + +``h`` + HI register. + +``v`` + Vector registers. + +``z`` + Stack pointer register (SP). + +``Q`` + A memory address which uses a base register with a short offset + or with a index register with its scale. + +``W`` + A memory address which uses a base register with a index register + with its scale. + +.. only:: gccint + + The C-SKY back end supports a large set of additional constraints + that are only useful for instruction selection or splitting rather + than inline asm, such as constraints representing constant integer + ranges accepted by particular instruction encodings. + Refer to the source code for details. + +Epiphany---:samp:`{config/epiphany/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``U16`` + An unsigned 16-bit constant. + +``K`` + An unsigned 5-bit constant. + +``L`` + A signed 11-bit constant. + +``Cm1`` + A signed 11-bit constant added to -1. + Can only match when the :option:`-m1reg-reg` option is active. + +``Cl1`` + Left-shift of -1, i.e., a bit mask with a block of leading ones, the rest + being a block of trailing zeroes. + Can only match when the :option:`-m1reg-reg` option is active. + +``Cr1`` + Right-shift of -1, i.e., a bit mask with a trailing block of ones, the + rest being zeroes. Or to put it another way, one less than a power of two. + Can only match when the :option:`-m1reg-reg` option is active. + +``Cal`` + Constant for arithmetic/logical operations. + This is like ``i``, except that for position independent code, + no symbols / expressions needing relocations are allowed. + +``Csy`` + Symbolic constant for call/jump instruction. + +``Rcs`` + The register class usable in short insns. This is a register class + constraint, and can thus drive register allocation. + This constraint won't match unless :option:`-mprefer-short-insn-regs` is + in effect. + +``Rsc`` + The register class of registers that can be used to hold a + sibcall call address. I.e., a caller-saved register. + +``Rct`` + Core control register class. + +``Rgs`` + The register group usable in short insns. + This constraint does not use a register class, so that it only + passively matches suitable registers, and doesn't drive register allocation. + +.. only:: gccint + + ``Car`` + Constant suitable for the addsi3_r pattern. This is a valid offset + For byte, halfword, or word addressing. + +``Rra`` + Matches the return address if it can be replaced with the link register. + +``Rcc`` + Matches the integer condition code register. + +``Sra`` + Matches the return address if it is in a stack slot. + +``Cfm`` + Matches control register values to switch fp mode, which are encapsulated in + ``UNSPEC_FP_MODE``. + +FRV---:samp:`{config/frv/frv.h}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``a`` + Register in the class ``ACC_REGS`` (``acc0`` to ``acc7``). + +``b`` + Register in the class ``EVEN_ACC_REGS`` (``acc0`` to ``acc7``). + +``c`` + Register in the class ``CC_REGS`` (``fcc0`` to ``fcc3`` and + ``icc0`` to ``icc3``). + +``d`` + Register in the class ``GPR_REGS`` (``gr0`` to ``gr63``). + +``e`` + Register in the class ``EVEN_REGS`` (``gr0`` to ``gr63``). + Odd registers are excluded not in the class but through the use of a machine + mode larger than 4 bytes. + +``f`` + Register in the class ``FPR_REGS`` (``fr0`` to ``fr63``). + +``h`` + Register in the class ``FEVEN_REGS`` (``fr0`` to ``fr63``). + Odd registers are excluded not in the class but through the use of a machine + mode larger than 4 bytes. + +``l`` + Register in the class ``LR_REG`` (the ``lr`` register). + +``q`` + Register in the class ``QUAD_REGS`` (``gr2`` to ``gr63``). + Register numbers not divisible by 4 are excluded not in the class but through + the use of a machine mode larger than 8 bytes. + +``t`` + Register in the class ``ICC_REGS`` (``icc0`` to ``icc3``). + +``u`` + Register in the class ``FCC_REGS`` (``fcc0`` to ``fcc3``). + +``v`` + Register in the class ``ICR_REGS`` (``cc4`` to ``cc7``). + +``w`` + Register in the class ``FCR_REGS`` (``cc0`` to ``cc3``). + +``x`` + Register in the class ``QUAD_FPR_REGS`` (``fr0`` to ``fr63``). + Register numbers not divisible by 4 are excluded not in the class but through + the use of a machine mode larger than 8 bytes. + +``z`` + Register in the class ``SPR_REGS`` (``lcr`` and ``lr``). + +``A`` + Register in the class ``QUAD_ACC_REGS`` (``acc0`` to ``acc7``). + +``B`` + Register in the class ``ACCG_REGS`` (``accg0`` to ``accg7``). + +``C`` + Register in the class ``CR_REGS`` (``cc0`` to ``cc7``). + +``G`` + Floating point constant zero + +``I`` + 6-bit signed integer constant + +``J`` + 10-bit signed integer constant + +``L`` + 16-bit signed integer constant + +``M`` + 16-bit unsigned integer constant + +``N`` + 12-bit signed integer constant that is negative---i.e. in the + range of -2048 to -1 + +``O`` + Constant zero + +``P`` + 12-bit signed integer constant that is greater than zero---i.e. in the + range of 1 to 2047. + +FT32---:samp:`{config/ft32/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``A`` + An absolute address + +``B`` + An offset address + +``W`` + A register indirect memory operand + +``e`` + An offset address. + +``f`` + An offset address. + +``O`` + The constant zero or one + +``I`` + A 16-bit signed constant (-32768 ... 32767) + +``w`` + A bitfield mask suitable for bext or bins + +``x`` + An inverted bitfield mask suitable for bext or bins + +``L`` + A 16-bit unsigned constant, multiple of 4 (0 ... 65532) + +``S`` + A 20-bit signed constant (-524288 ... 524287) + +``b`` + A constant for a bitfield width (1 ... 16) + +``KA`` + A 10-bit signed constant (-512 ... 511) + +Hewlett-Packard PA-RISC---:samp:`{config/pa/pa.h}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``a`` + General register 1 + +``f`` + Floating point register + +``q`` + Shift amount register + +``x`` + Floating point register (deprecated) + +``y`` + Upper floating point register (32-bit), floating point register (64-bit) + +``Z`` + Any register + +``I`` + Signed 11-bit integer constant + +``J`` + Signed 14-bit integer constant + +``K`` + Integer constant that can be deposited with a ``zdepi`` instruction + +``L`` + Signed 5-bit integer constant + +``M`` + Integer constant 0 + +``N`` + Integer constant that can be loaded with a ``ldil`` instruction + +``O`` + Integer constant whose value plus one is a power of 2 + +``P`` + Integer constant that can be used for ``and`` operations in ``depi`` + and ``extru`` instructions + +``S`` + Integer constant 31 + +``U`` + Integer constant 63 + +``G`` + Floating-point constant 0.0 + +``A`` + A ``lo_sum`` data-linkage-table memory operand + +``Q`` + A memory operand that can be used as the destination operand of an + integer store instruction + +``R`` + A scaled or unscaled indexed memory operand + +``T`` + A memory operand for floating-point loads and stores + +``W`` + A register indirect memory operand + +Intel IA-64---:samp:`{config/ia64/ia64.h}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``a`` + General register ``r0`` to ``r3`` for ``addl`` instruction + +``b`` + Branch register + +``c`` + Predicate register (:samp:`c` as in 'conditional') + +``d`` + Application register residing in M-unit + +``e`` + Application register residing in I-unit + +``f`` + Floating-point register + +``m`` + Memory operand. If used together with :samp:`<` or :samp:`>`, + the operand can have postincrement and postdecrement which + require printing with :samp:`%Pn` on IA-64. + +``G`` + Floating-point constant 0.0 or 1.0 + +``I`` + 14-bit signed integer constant + +``J`` + 22-bit signed integer constant + +``K`` + 8-bit signed integer constant for logical instructions + +``L`` + 8-bit adjusted signed integer constant for compare pseudo-ops + +``M`` + 6-bit unsigned integer constant for shift counts + +``N`` + 9-bit signed integer constant for load and store postincrements + +``O`` + The constant zero + +``P`` + 0 or -1 for ``dep`` instruction + +``Q`` + Non-volatile memory for floating-point loads and stores + +``R`` + Integer constant in the range 1 to 4 for ``shladd`` instruction + +``S`` + Memory operand except postincrement and postdecrement. This is + now roughly the same as :samp:`m` when not used together with :samp:`<` + or :samp:`>`. + +M32C---:samp:`{config/m32c/m32c.cc}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``Rsp`` ``Rfb`` ``Rsb`` + :samp:`$sp`, :samp:`$fb`, :samp:`$sb`. + +``Rcr`` + Any control register, when they're 16 bits wide (nothing if control + registers are 24 bits wide) + +``Rcl`` + Any control register, when they're 24 bits wide. + +``R0w`` ``R1w`` ``R2w`` ``R3w`` + $r0, $r1, $r2, $r3. + +``R02`` + $r0 or $r2, or $r2r0 for 32 bit values. + +``R13`` + $r1 or $r3, or $r3r1 for 32 bit values. + +``Rdi`` + A register that can hold a 64 bit value. + +``Rhl`` + $r0 or $r1 (registers with addressable high/low bytes) + +``R23`` + $r2 or $r3 + +``Raa`` + Address registers + +``Raw`` + Address registers when they're 16 bits wide. + +``Ral`` + Address registers when they're 24 bits wide. + +``Rqi`` + Registers that can hold QI values. + +``Rad`` + Registers that can be used with displacements ($a0, $a1, $sb). + +``Rsi`` + Registers that can hold 32 bit values. + +``Rhi`` + Registers that can hold 16 bit values. + +``Rhc`` + Registers chat can hold 16 bit values, including all control + registers. + +``Rra`` + $r0 through R1, plus $a0 and $a1. + +``Rfl`` + The flags register. + +``Rmm`` + The memory-based pseudo-registers $mem0 through $mem15. + +``Rpi`` + Registers that can hold pointers (16 bit registers for r8c, m16c; 24 + bit registers for m32cm, m32c). + +``Rpa`` + Matches multiple registers in a PARALLEL to form a larger register. + Used to match function return values. + +``Is3`` + -8 ... 7 + +``IS1`` + -128 ... 127 + +``IS2`` + -32768 ... 32767 + +``IU2`` + 0 ... 65535 + +``In4`` + -8 ... -1 or 1 ... 8 + +``In5`` + -16 ... -1 or 1 ... 16 + +``In6`` + -32 ... -1 or 1 ... 32 + +``IM2`` + -65536 ... -1 + +``Ilb`` + An 8 bit value with exactly one bit set. + +``Ilw`` + A 16 bit value with exactly one bit set. + +``Sd`` + The common src/dest memory addressing modes. + +``Sa`` + Memory addressed using $a0 or $a1. + +``Si`` + Memory addressed with immediate addresses. + +``Ss`` + Memory addressed using the stack pointer ($sp). + +``Sf`` + Memory addressed using the frame base register ($fb). + +``Ss`` + Memory addressed using the small base register ($sb). + +``S1`` + $r1h + +LoongArch---:samp:`{config/loongarch/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``f`` + A floating-point register (if available). + +``k`` + A memory operand whose address is formed by a base register and + (optionally scaled) index register. + +``l`` + A signed 16-bit constant. + +``m`` + A memory operand whose address is formed by a base register and offset + that is suitable for use in instructions with the same addressing mode + as ``st.w`` and ``ld.w``. + +``I`` + A signed 12-bit constant (for arithmetic instructions). + +``K`` + An unsigned 12-bit constant (for logic instructions). + +``ZB`` + An address that is held in a general-purpose register. + The offset is zero. + +``ZC`` + A memory operand whose address is formed by a base register and offset + that is suitable for use in instructions with the same addressing mode + as ``ll.w`` and ``sc.w``. + +MicroBlaze---:samp:`{config/microblaze/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``d`` + A general register (``r0`` to ``r31``). + +``z`` + A status register (``rmsr``, ``$fcc1`` to ``$fcc7``). + +MIPS---:samp:`{config/mips/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``d`` + A general-purpose register. This is equivalent to ``r`` unless + generating MIPS16 code, in which case the MIPS16 register set is used. + +``f`` + A floating-point register (if available). + +``h`` + Formerly the ``hi`` register. This constraint is no longer supported. + +``l`` + The ``lo`` register. Use this register to store values that are + no bigger than a word. + +``x`` + The concatenated ``hi`` and ``lo`` registers. Use this register + to store doubleword values. + +``c`` + A register suitable for use in an indirect jump. This will always be + ``$25`` for :option:`-mabicalls`. + +``v`` + Register ``$3``. Do not use this constraint in new code; + it is retained only for compatibility with glibc. + +``y`` + Equivalent to ``r`` ; retained for backwards compatibility. + +``z`` + A floating-point condition code register. + +``I`` + A signed 16-bit constant (for arithmetic instructions). + +``J`` + Integer zero. + +``K`` + An unsigned 16-bit constant (for logic instructions). + +``L`` + A signed 32-bit constant in which the lower 16 bits are zero. + Such constants can be loaded using ``lui``. + +``M`` + A constant that cannot be loaded using ``lui``, ``addiu`` + or ``ori``. + +``N`` + A constant in the range -65535 to -1 (inclusive). + +``O`` + A signed 15-bit constant. + +``P`` + A constant in the range 1 to 65535 (inclusive). + +``G`` + Floating-point zero. + +``R`` + An address that can be used in a non-macro load or store. + +``ZC`` + A memory operand whose address is formed by a base register and offset + that is suitable for use in instructions with the same addressing mode + as ``ll`` and ``sc``. + +``ZD`` + An address suitable for a ``prefetch`` instruction, or for any other + instruction with the same addressing mode as ``prefetch``. + +Motorola 680x0---:samp:`{config/m68k/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``a`` + Address register + +``d`` + Data register + +``f`` + 68881 floating-point register, if available + +``I`` + Integer in the range 1 to 8 + +``J`` + 16-bit signed number + +``K`` + Signed number whose magnitude is greater than 0x80 + +``L`` + Integer in the range -8 to -1 + +``M`` + Signed number whose magnitude is greater than 0x100 + +``N`` + Range 24 to 31, rotatert:SI 8 to 1 expressed as rotate + +``O`` + 16 (for rotate using swap) + +``P`` + Range 8 to 15, rotatert:HI 8 to 1 expressed as rotate + +``R`` + Numbers that mov3q can handle + +``G`` + Floating point constant that is not a 68881 constant + +``S`` + Operands that satisfy 'm' when -mpcrel is in effect + +``T`` + Operands that satisfy 's' when -mpcrel is not in effect + +``Q`` + Address register indirect addressing mode + +``U`` + Register offset addressing + +``W`` + const_call_operand + +``Cs`` + symbol_ref or const + +``Ci`` + const_int + +``C0`` + const_int 0 + +``Cj`` + Range of signed numbers that don't fit in 16 bits + +``Cmvq`` + Integers valid for mvq + +``Capsw`` + Integers valid for a moveq followed by a swap + +``Cmvz`` + Integers valid for mvz + +``Cmvs`` + Integers valid for mvs + +``Ap`` + push_operand + +``Ac`` + Non-register operands allowed in clr + +Moxie---:samp:`{config/moxie/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``A`` + An absolute address + +``B`` + An offset address + +``W`` + A register indirect memory operand + +``I`` + A constant in the range of 0 to 255. + +``N`` + A constant in the range of 0 to -255. + +MSP430---:samp:`{config/msp430/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``R12`` + Register R12. + +``R13`` + Register R13. + +``K`` + Integer constant 1. + +``L`` + Integer constant -1^20..1^19. + +``M`` + Integer constant 1-4. + +``Ya`` + Memory references which do not require an extended MOVX instruction. + +``Yl`` + Memory reference, labels only. + +``Ys`` + Memory reference, stack only. + +NDS32---:samp:`{config/nds32/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``w`` + LOW register class $r0 to $r7 constraint for V3/V3M ISA. + +``l`` + LOW register class $r0 to $r7. + +``d`` + MIDDLE register class $r0 to $r11, $r16 to $r19. + +``h`` + HIGH register class $r12 to $r14, $r20 to $r31. + +``t`` + Temporary assist register $ta (i.e. $r15). + +``k`` + Stack register $sp. + +``Iu03`` + Unsigned immediate 3-bit value. + +``In03`` + Negative immediate 3-bit value in the range of -7--0. + +``Iu04`` + Unsigned immediate 4-bit value. + +``Is05`` + Signed immediate 5-bit value. + +``Iu05`` + Unsigned immediate 5-bit value. + +``In05`` + Negative immediate 5-bit value in the range of -31--0. + +``Ip05`` + Unsigned immediate 5-bit value for movpi45 instruction with range 16--47. + +``Iu06`` + Unsigned immediate 6-bit value constraint for addri36.sp instruction. + +``Iu08`` + Unsigned immediate 8-bit value. + +``Iu09`` + Unsigned immediate 9-bit value. + +``Is10`` + Signed immediate 10-bit value. + +``Is11`` + Signed immediate 11-bit value. + +``Is15`` + Signed immediate 15-bit value. + +``Iu15`` + Unsigned immediate 15-bit value. + +``Ic15`` + A constant which is not in the range of imm15u but ok for bclr instruction. + +``Ie15`` + A constant which is not in the range of imm15u but ok for bset instruction. + +``It15`` + A constant which is not in the range of imm15u but ok for btgl instruction. + +``Ii15`` + A constant whose compliment value is in the range of imm15u + and ok for bitci instruction. + +``Is16`` + Signed immediate 16-bit value. + +``Is17`` + Signed immediate 17-bit value. + +``Is19`` + Signed immediate 19-bit value. + +``Is20`` + Signed immediate 20-bit value. + +``Ihig`` + The immediate value that can be simply set high 20-bit. + +``Izeb`` + The immediate value 0xff. + +``Izeh`` + The immediate value 0xffff. + +``Ixls`` + The immediate value 0x01. + +``Ix11`` + The immediate value 0x7ff. + +``Ibms`` + The immediate value with power of 2. + +``Ifex`` + The immediate value with power of 2 minus 1. + +``U33`` + Memory constraint for 333 format. + +``U45`` + Memory constraint for 45 format. + +``U37`` + Memory constraint for 37 format. + +Nios II family---:samp:`{config/nios2/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``I`` + Integer that is valid as an immediate operand in an + instruction taking a signed 16-bit number. Range + -32768 to 32767. + +``J`` + Integer that is valid as an immediate operand in an + instruction taking an unsigned 16-bit number. Range + 0 to 65535. + +``K`` + Integer that is valid as an immediate operand in an + instruction taking only the upper 16-bits of a + 32-bit number. Range 32-bit numbers with the lower + 16-bits being 0. + +``L`` + Integer that is valid as an immediate operand for a + shift instruction. Range 0 to 31. + +``M`` + Integer that is valid as an immediate operand for + only the value 0. Can be used in conjunction with + the format modifier ``z`` to use ``r0`` + instead of ``0`` in the assembly output. + +``N`` + Integer that is valid as an immediate operand for + a custom instruction opcode. Range 0 to 255. + +``P`` + An immediate operand for R2 andchi/andci instructions. + +``S`` + Matches immediates which are addresses in the small + data section and therefore can be added to ``gp`` + as a 16-bit immediate to re-create their 32-bit value. + +``U`` + Matches constants suitable as an operand for the rdprs and + cache instructions. + +``v`` + A memory operand suitable for Nios II R2 load/store + exclusive instructions. + +``w`` + A memory operand suitable for load/store IO and cache + instructions. + +.. only:: gccint + + ``T`` + A ``const`` wrapped ``UNSPEC`` expression, + representing a supported PIC or TLS relocation. + +OpenRISC---:samp:`{config/or1k/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``I`` + Integer that is valid as an immediate operand in an + instruction taking a signed 16-bit number. Range + -32768 to 32767. + +``K`` + Integer that is valid as an immediate operand in an + instruction taking an unsigned 16-bit number. Range + 0 to 65535. + +``M`` + Signed 16-bit constant shifted left 16 bits. (Used with ``l.movhi``) + +``O`` + Zero + +.. only:: gccint + + ``c`` + Register usable for sibcalls. + +PDP-11---:samp:`{config/pdp11/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``a`` + Floating point registers AC0 through AC3. These can be loaded from/to + memory with a single instruction. + +``d`` + Odd numbered general registers (R1, R3, R5). These are used for + 16-bit multiply operations. + +``D`` + A memory reference that is encoded within the opcode, but not + auto-increment or auto-decrement. + +``f`` + Any of the floating point registers (AC0 through AC5). + +``G`` + Floating point constant 0. + +``h`` + Floating point registers AC4 and AC5. These cannot be loaded from/to + memory with a single instruction. + +``I`` + An integer constant that fits in 16 bits. + +``J`` + An integer constant whose low order 16 bits are zero. + +``K`` + An integer constant that does not meet the constraints for codes + :samp:`I` or :samp:`J`. + +``L`` + The integer constant 1. + +``M`` + The integer constant -1. + +``N`` + The integer constant 0. + +``O`` + Integer constants 0 through 3; shifts by these + amounts are handled as multiple single-bit shifts rather than a single + variable-length shift. + +``Q`` + A memory reference which requires an additional word (address or + offset) after the opcode. + +``R`` + A memory reference that is encoded within the opcode. + +PowerPC and IBM RS6000---:samp:`{config/rs6000/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``r`` + A general purpose register (GPR), ``r0``... ``r31``. + +``b`` + A base register. Like ``r``, but ``r0`` is not allowed, so + ``r1``... ``r31``. + +``f`` + A floating point register (FPR), ``f0``... ``f31``. + +``d`` + A floating point register. This is the same as ``f`` nowadays; + historically ``f`` was for single-precision and ``d`` was for + double-precision floating point. + +``v`` + An Altivec vector register (VR), ``v0``... ``v31``. + +``wa`` + A VSX register (VSR), ``vs0``... ``vs63``. This is either an + FPR (``vs0``... ``vs31`` are ``f0``... ``f31``) or a VR + (``vs32``... ``vs63`` are ``v0``... ``v31``). + + When using ``wa``, you should use the ``%x`` output modifier, so that + the correct register number is printed. For example: + + .. code-block:: c++ + + asm ("xvadddp %x0,%x1,%x2" + : "=wa" (v1) + : "wa" (v2), "wa" (v3)); + + You should not use ``%x`` for ``v`` operands: + + .. code-block:: c++ + + asm ("xsaddqp %0,%1,%2" + : "=v" (v1) + : "v" (v2), "v" (v3)); + +.. only:: gccint + + ``h`` + A special register (``vrsave``, ``ctr``, or ``lr``). + +``c`` + The count register, ``ctr``. + +``l`` + The link register, ``lr``. + +``x`` + Condition register field 0, ``cr0``. + +``y`` + Any condition register field, ``cr0``... ``cr7``. + +.. only:: gccint + + ``z`` + The carry bit, ``XER[CA]``. + + ``we`` + Like ``wa``, if :option:`-mpower9-vector` and :option:`-m64` are used; + otherwise, ``NO_REGS``. + + ``wn`` + No register (``NO_REGS``). + + ``wr`` + Like ``r``, if :option:`-mpowerpc64` is used; otherwise, ``NO_REGS``. + + ``wx`` + Like ``d``, if :option:`-mpowerpc-gfxopt` is used; otherwise, ``NO_REGS``. + + ``wA`` + Like ``b``, if :option:`-mpowerpc64` is used; otherwise, ``NO_REGS``. + + ``wB`` + Signed 5-bit constant integer that can be loaded into an Altivec register. + + ``wE`` + Vector constant that can be loaded with the XXSPLTIB instruction. + + ``wF`` + Memory operand suitable for power8 GPR load fusion. + + ``wL`` + Int constant that is the element number mfvsrld accesses in a vector. + + ``wM`` + Match vector constant with all 1's if the XXLORC instruction is available. + + ``wO`` + Memory operand suitable for the ISA 3.0 vector d-form instructions. + + ``wQ`` + Memory operand suitable for the load/store quad instructions. + + ``wS`` + Vector constant that can be loaded with XXSPLTIB & sign extension. + + ``wY`` + A memory operand for a DS-form instruction. + + ``wZ`` + An indexed or indirect memory operand, ignoring the bottom 4 bits. + +``I`` + A signed 16-bit constant. + +``J`` + An unsigned 16-bit constant shifted left 16 bits (use ``L`` instead + for ``SImode`` constants). + +``K`` + An unsigned 16-bit constant. + +``L`` + A signed 16-bit constant shifted left 16 bits. + +.. only:: gccint + + ``M`` + An integer constant greater than 31. + + ``N`` + An exact power of 2. + + ``O`` + The integer constant zero. + + ``P`` + A constant whose negation is a signed 16-bit constant. + +``eI`` + A signed 34-bit integer constant if prefixed instructions are supported. + +``eQ`` + An IEEE 128-bit constant that can be loaded into a VSX register with + the ``lxvkq`` instruction. + +.. only:: gccint + + ``G`` + A floating point constant that can be loaded into a register with one + instruction per word. + + ``H`` + A floating point constant that can be loaded into a register using + three instructions. + +``m`` + A memory operand. + Normally, ``m`` does not allow addresses that update the base register. + If the ``<`` or ``>`` constraint is also used, they are allowed and + therefore on PowerPC targets in that case it is only safe + to use ``m<>`` in an ``asm`` statement if that ``asm`` statement + accesses the operand exactly once. The ``asm`` statement must also + use ``%U`` as a placeholder for the 'update' flag in the + corresponding load or store instruction. For example: + + .. code-block:: c++ + + asm ("st%U0 %1,%0" : "=m<>" (mem) : "r" (val)); + + is correct but: + + .. code-block:: c++ + + asm ("st %1,%0" : "=m<>" (mem) : "r" (val)); + + is not. + +.. only:: gccint + + ``es`` + A 'stable' memory operand; that is, one which does not include any + automodification of the base register. This used to be useful when + ``m`` allowed automodification of the base register, but as those + are now only allowed when ``<`` or ``>`` is used, ``es`` is + basically the same as ``m`` without ``<`` and ``>``. + +``Q`` + A memory operand addressed by just a base register. + +.. only:: gccint + + ``Y`` + A memory operand for a DQ-form instruction. + +``Z`` + A memory operand accessed with indexed or indirect addressing. + +.. only:: gccint + + ``R`` + An AIX TOC entry. + +``a`` + An indexed or indirect address. + +.. only:: gccint + + ``U`` + A V.4 small data reference. + + ``W`` + A vector constant that does not require memory. + + ``j`` + The zero vector constant. + +PRU---:samp:`{config/pru/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``I`` + An unsigned 8-bit integer constant. + +``J`` + An unsigned 16-bit integer constant. + +``L`` + An unsigned 5-bit integer constant (for shift counts). + +``T`` + A text segment (program memory) constant label. + +``Z`` + Integer constant zero. + +RL78---:samp:`{config/rl78/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``Int3`` + An integer constant in the range 1 ... 7. + +``Int8`` + An integer constant in the range 0 ... 255. + +``J`` + An integer constant in the range -255 ... 0 + +``K`` + The integer constant 1. + +``L`` + The integer constant -1. + +``M`` + The integer constant 0. + +``N`` + The integer constant 2. + +``O`` + The integer constant -2. + +``P`` + An integer constant in the range 1 ... 15. + +``Qbi`` + The built-in compare types--eq, ne, gtu, ltu, geu, and leu. + +``Qsc`` + The synthetic compare types--gt, lt, ge, and le. + +``Wab`` + A memory reference with an absolute address. + +``Wbc`` + A memory reference using ``BC`` as a base register, with an optional offset. + +``Wca`` + A memory reference using ``AX``, ``BC``, ``DE``, or ``HL`` for the address, for calls. + +``Wcv`` + A memory reference using any 16-bit register pair for the address, for calls. + +``Wd2`` + A memory reference using ``DE`` as a base register, with an optional offset. + +``Wde`` + A memory reference using ``DE`` as a base register, without any offset. + +``Wfr`` + Any memory reference to an address in the far address space. + +``Wh1`` + A memory reference using ``HL`` as a base register, with an optional one-byte offset. + +``Whb`` + A memory reference using ``HL`` as a base register, with ``B`` or ``C`` as the index register. + +``Whl`` + A memory reference using ``HL`` as a base register, without any offset. + +``Ws1`` + A memory reference using ``SP`` as a base register, with an optional one-byte offset. + +``Y`` + Any memory reference to an address in the near address space. + +``A`` + The ``AX`` register. + +``B`` + The ``BC`` register. + +``D`` + The ``DE`` register. + +``R`` + ``A`` through ``L`` registers. + +``S`` + The ``SP`` register. + +``T`` + The ``HL`` register. + +``Z08W`` + The 16-bit ``R8`` register. + +``Z10W`` + The 16-bit ``R10`` register. + +``Zint`` + The registers reserved for interrupts (``R24`` to ``R31``). + +``a`` + The ``A`` register. + +``b`` + The ``B`` register. + +``c`` + The ``C`` register. + +``d`` + The ``D`` register. + +``e`` + The ``E`` register. + +``h`` + The ``H`` register. + +``l`` + The ``L`` register. + +``v`` + The virtual registers. + +``w`` + The ``PSW`` register. + +``x`` + The ``X`` register. + +RISC-V---:samp:`{config/riscv/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``f`` + A floating-point register (if available). + +``I`` + An I-type 12-bit signed immediate. + +``J`` + Integer zero. + +``K`` + A 5-bit unsigned immediate for CSR access instructions. + +``A`` + An address that is held in a general-purpose register. + +``S`` + A constraint that matches an absolute symbolic address. + +RX---:samp:`{config/rx/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``Q`` + An address which does not involve register indirect addressing or + pre/post increment/decrement addressing. + +``Symbol`` + A symbol reference. + +``Int08`` + A constant in the range -256 to 255, inclusive. + +``Sint08`` + A constant in the range -128 to 127, inclusive. + +``Sint16`` + A constant in the range -32768 to 32767, inclusive. + +``Sint24`` + A constant in the range -8388608 to 8388607, inclusive. + +``Uint04`` + A constant in the range 0 to 15, inclusive. + +S/390 and zSeries---:samp:`{config/s390/s390.h}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``a`` + Address register (general purpose register except r0) + +``c`` + Condition code register + +``d`` + Data register (arbitrary general purpose register) + +``f`` + Floating-point register + +``I`` + Unsigned 8-bit constant (0--255) + +``J`` + Unsigned 12-bit constant (0--4095) + +``K`` + Signed 16-bit constant (-32768--32767) + +``L`` + Value appropriate as displacement. + + ``(0..4095)`` + for short displacement + + ``(-524288..524287)`` + for long displacement + +``M`` + Constant integer with a value of 0x7fffffff. + +``N`` + Multiple letter constraint followed by 4 parameter letters. + + ``0..9:`` + number of the part counting from most to least significant + + ``H,Q:`` + mode of the part + + ``D,S,H:`` + mode of the containing operand + + ``0,F:`` + value of the other parts (F---all bits set) + + The constraint matches if the specified part of a constant + has a value different from its other parts. + +``Q`` + Memory reference without index register and with short displacement. + +``R`` + Memory reference with index register and short displacement. + +``S`` + Memory reference without index register but with long displacement. + +``T`` + Memory reference with index register and long displacement. + +``U`` + Pointer with short displacement. + +``W`` + Pointer with long displacement. + +``Y`` + Shift count operand. + +SPARC---:samp:`{config/sparc/sparc.h}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``f`` + Floating-point register on the SPARC-V8 architecture and + lower floating-point register on the SPARC-V9 architecture. + +``e`` + Floating-point register. It is equivalent to :samp:`f` on the + SPARC-V8 architecture and contains both lower and upper + floating-point registers on the SPARC-V9 architecture. + +``c`` + Floating-point condition code register. + +``d`` + Lower floating-point register. It is only valid on the SPARC-V9 + architecture when the Visual Instruction Set is available. + +``b`` + Floating-point register. It is only valid on the SPARC-V9 architecture + when the Visual Instruction Set is available. + +``h`` + 64-bit global or out register for the SPARC-V8+ architecture. + +``C`` + The constant all-ones, for floating-point. + +``A`` + Signed 5-bit constant + +``D`` + A vector constant + +``I`` + Signed 13-bit constant + +``J`` + Zero + +``K`` + 32-bit constant with the low 12 bits clear (a constant that can be + loaded with the ``sethi`` instruction) + +``L`` + A constant in the range supported by ``movcc`` instructions (11-bit + signed immediate) + +``M`` + A constant in the range supported by ``movrcc`` instructions (10-bit + signed immediate) + +``N`` + Same as :samp:`K`, except that it verifies that bits that are not in the + lower 32-bit range are all zero. Must be used instead of :samp:`K` for + modes wider than ``SImode`` + +``O`` + The constant 4096 + +``G`` + Floating-point zero + +``H`` + Signed 13-bit constant, sign-extended to 32 or 64 bits + +``P`` + The constant -1 + +``Q`` + Floating-point constant whose integral representation can + be moved into an integer register using a single sethi + instruction + +``R`` + Floating-point constant whose integral representation can + be moved into an integer register using a single mov + instruction + +``S`` + Floating-point constant whose integral representation can + be moved into an integer register using a high/lo_sum + instruction sequence + +``T`` + Memory address aligned to an 8-byte boundary + +``U`` + Even register + +``W`` + Memory address for :samp:`e` constraint registers + +``w`` + Memory address with only a base register + +``Y`` + Vector zero + +TI C6X family---:samp:`{config/c6x/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``a`` + Register file A (A0--A31). + +``b`` + Register file B (B0--B31). + +``A`` + Predicate registers in register file A (A0--A2 on C64X and + higher, A1 and A2 otherwise). + +``B`` + Predicate registers in register file B (B0--B2). + +``C`` + A call-used register in register file B (B0--B9, B16--B31). + +``Da`` + Register file A, excluding predicate registers (A3--A31, + plus A0 if not C64X or higher). + +``Db`` + Register file B, excluding predicate registers (B3--B31). + +``Iu4`` + Integer constant in the range 0 ... 15. + +``Iu5`` + Integer constant in the range 0 ... 31. + +``In5`` + Integer constant in the range -31 ... 0. + +``Is5`` + Integer constant in the range -16 ... 15. + +``I5x`` + Integer constant that can be the operand of an ADDA or a SUBA insn. + +``IuB`` + Integer constant in the range 0 ... 65535. + +``IsB`` + Integer constant in the range -32768 ... 32767. + +``IsC`` + Integer constant in the range -2^{20} ... 2^{20} - 1. + +``Jc`` + Integer constant that is a valid mask for the clr instruction. + +``Js`` + Integer constant that is a valid mask for the set instruction. + +``Q`` + Memory location with A base register. + +``R`` + Memory location with B base register. + +.. only:: gccint + + ``S0`` + On C64x+ targets, a GP-relative small data reference. + + ``S1`` + Any kind of ``SYMBOL_REF``, for use in a call address. + + ``Si`` + Any kind of immediate operand, unless it matches the S0 constraint. + + ``T`` + Memory location with B base register, but not using a long offset. + + ``W`` + A memory operand with an address that cannot be used in an unaligned access. + +``Z`` + Register B14 (aka DP). + +Visium---:samp:`{config/visium/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``b`` + EAM register ``mdb`` + +``c`` + EAM register ``mdc`` + +``f`` + Floating point register + +.. only:: gccint + + ``k`` + Register for sibcall optimization + +``l`` + General register, but not ``r29``, ``r30`` and ``r31`` + +``t`` + Register ``r1`` + +``u`` + Register ``r2`` + +``v`` + Register ``r3`` + +``G`` + Floating-point constant 0.0 + +``J`` + Integer constant in the range 0 .. 65535 (16-bit immediate) + +``K`` + Integer constant in the range 1 .. 31 (5-bit immediate) + +``L`` + Integer constant in the range -65535 .. -1 (16-bit negative immediate) + +``M`` + Integer constant -1 + +``O`` + Integer constant 0 + +``P`` + Integer constant 32 + +x86 family---:samp:`{config/i386/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``R`` + Legacy register---the eight integer registers available on all + i386 processors (``a``, ``b``, ``c``, ``d``, + ``si``, ``di``, ``bp``, ``sp``). + +``q`` + Any register accessible as ``rl``. In 32-bit mode, ``a``, + ``b``, ``c``, and ``d`` ; in 64-bit mode, any integer register. + +``Q`` + Any register accessible as ``rh`` : ``a``, ``b``, + ``c``, and ``d``. + +.. only:: gccint + + ``l`` + Any register that can be used as the index in a base+index memory + access: that is, any general register except the stack pointer. + +``a`` + The ``a`` register. + +``b`` + The ``b`` register. + +``c`` + The ``c`` register. + +``d`` + The ``d`` register. + +``S`` + The ``si`` register. + +``D`` + The ``di`` register. + +``A`` + The ``a`` and ``d`` registers. This class is used for instructions + that return double word results in the ``ax:dx`` register pair. Single + word values will be allocated either in ``ax`` or ``dx``. + For example on i386 the following implements ``rdtsc`` : + + .. code-block:: c++ + + unsigned long long rdtsc (void) + { + unsigned long long tick; + __asm__ __volatile__("rdtsc":"=A"(tick)); + return tick; + } + + This is not correct on x86-64 as it would allocate tick in either ``ax`` + or ``dx``. You have to use the following variant instead: + + .. code-block:: c++ + + unsigned long long rdtsc (void) + { + unsigned int tickl, tickh; + __asm__ __volatile__("rdtsc":"=a"(tickl),"=d"(tickh)); + return ((unsigned long long)tickh << 32)|tickl; + } + +``U`` + The call-clobbered integer registers. + +``f`` + Any 80387 floating-point (stack) register. + +``t`` + Top of 80387 floating-point stack (``%st(0)``). + +``u`` + Second from top of 80387 floating-point stack (``%st(1)``). + +.. only:: gccint + + ``Yk`` + Any mask register that can be used as a predicate, i.e. ``k1-k7``. + + ``k`` + Any mask register. + +``y`` + Any MMX register. + +``x`` + Any SSE register. + +``v`` + Any EVEX encodable SSE register (``%xmm0-%xmm31``). + +.. only:: gccint + + ``w`` + Any bound register. + +``Yz`` + First SSE register (``%xmm0``). + +.. only:: gccint + + ``Yi`` + Any SSE register, when SSE2 and inter-unit moves are enabled. + + ``Yj`` + Any SSE register, when SSE2 and inter-unit moves from vector registers are enabled. + + ``Ym`` + Any MMX register, when inter-unit moves are enabled. + + ``Yn`` + Any MMX register, when inter-unit moves from vector registers are enabled. + + ``Yp`` + Any integer register when ``TARGET_PARTIAL_REG_STALL`` is disabled. + + ``Ya`` + Any integer register when zero extensions with ``AND`` are disabled. + + ``Yb`` + Any register that can be used as the GOT base when calling + + ``___tls_get_addr`` : that is, any general register except ``a`` + and ``sp`` registers, for :option:`-fno-plt` if linker supports it. + Otherwise, ``b`` register. + + ``Yf`` + Any x87 register when 80387 floating-point arithmetic is enabled. + + ``Yr`` + Lower SSE register when avoiding REX prefix and all SSE registers otherwise. + + ``Yv`` + For AVX512VL, any EVEX-encodable SSE register (``%xmm0-%xmm31``), + otherwise any SSE register. + + ``Yh`` + Any EVEX-encodable SSE register, that has number factor of four. + + ``Bf`` + Flags register operand. + + ``Bg`` + GOT memory operand. + + ``Bm`` + Vector memory operand. + + ``Bc`` + Constant memory operand. + +``Bn`` + Memory operand without REX prefix. + +``Bs`` + Sibcall memory operand. + +``Bw`` + Call memory operand. + +``Bz`` + Constant call address operand. + +``BC`` + SSE constant -1 operand. + +``I`` + Integer constant in the range 0 ... 31, for 32-bit shifts. + +``J`` + Integer constant in the range 0 ... 63, for 64-bit shifts. + +``K`` + Signed 8-bit integer constant. + +``L`` + ``0xFF`` or ``0xFFFF``, for andsi as a zero-extending move. + +``M`` + 0, 1, 2, or 3 (shifts for the ``lea`` instruction). + +``N`` + Unsigned 8-bit integer constant (for ``in`` and ``out`` + instructions). + +.. only:: gccint + + ``O`` + Integer constant in the range 0 ... 127, for 128-bit shifts. + +``G`` + Standard 80387 floating point constant. + +``C`` + SSE constant zero operand. + +``e`` + 32-bit signed integer constant, or a symbolic reference known + to fit that range (for immediate operands in sign-extending x86-64 + instructions). + +``We`` + 32-bit signed integer constant, or a symbolic reference known + to fit that range (for sign-extending conversion operations that + require non- ``VOIDmode`` immediate operands). + +``Wz`` + 32-bit unsigned integer constant, or a symbolic reference known + to fit that range (for zero-extending conversion operations that + require non- ``VOIDmode`` immediate operands). + +``Wd`` + 128-bit integer constant where both the high and low 64-bit word + satisfy the ``e`` constraint. + +``Z`` + 32-bit unsigned integer constant, or a symbolic reference known + to fit that range (for immediate operands in zero-extending x86-64 + instructions). + +``Tv`` + VSIB address operand. + +``Ts`` + Address operand without segment register. + +Xstormy16---:samp:`{config/stormy16/stormy16.h}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``a`` + Register r0. + +``b`` + Register r1. + +``c`` + Register r2. + +``d`` + Register r8. + +``e`` + Registers r0 through r7. + +``t`` + Registers r0 and r1. + +``y`` + The carry register. + +``z`` + Registers r8 and r9. + +``I`` + A constant between 0 and 3 inclusive. + +``J`` + A constant that has exactly one bit set. + +``K`` + A constant that has exactly one bit clear. + +``L`` + A constant between 0 and 255 inclusive. + +``M`` + A constant between -255 and 0 inclusive. + +``N`` + A constant between -3 and 0 inclusive. + +``O`` + A constant between 1 and 4 inclusive. + +``P`` + A constant between -4 and -1 inclusive. + +``Q`` + A memory reference that is a stack push. + +``R`` + A memory reference that is a stack pop. + +``S`` + A memory reference that refers to a constant address of known value. + +``T`` + The register indicated by Rx (not implemented yet). + +``U`` + A constant that is not between 2 and 15 inclusive. + +``Z`` + The constant 0. + +Xtensa---:samp:`{config/xtensa/constraints.md}` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``a`` + General-purpose 32-bit register + +``b`` + One-bit boolean register + +``A`` + MAC16 40-bit accumulator register + +``I`` + Signed 12-bit integer constant, for use in MOVI instructions + +``J`` + Signed 8-bit integer constant, for use in ADDI instructions + +``K`` + Integer constant valid for BccI instructions + +``L`` + Unsigned constant valid for BccUI instructions \ No newline at end of file diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 00000000000..f5558030ca8 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,3 @@ +Sphinx>=5.3 +furo +sphinx_copybutton diff --git a/gcc/d/doc/conf.py b/gcc/d/doc/conf.py new file mode 100644 index 00000000000..c33f28a2f7f --- /dev/null +++ b/gcc/d/doc/conf.py @@ -0,0 +1,30 @@ +# Configuration file for the Sphinx documentation builder. + +import sys +sys.path.append('../../..//doc') + +from baseconf import * + +name = 'gdc' +project = 'The GNU D Compiler' +copyright = '2006-2022 Free Software Foundation, Inc.' +authors = 'David Friedman, Iain Buclaw' + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +latex_documents = [ + ('index', f'{name}.tex', project, authors, 'manual'), +] + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('invoking-gdc', name, project, [authors], 1), +] + +texinfo_documents = [ + ('index', name, project, authors, None, None, None, True) +] + +set_common(name, globals()) \ No newline at end of file diff --git a/gcc/d/doc/copyright.rst b/gcc/d/doc/copyright.rst new file mode 100644 index 00000000000..5afce611a7a --- /dev/null +++ b/gcc/d/doc/copyright.rst @@ -0,0 +1,13 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the GPL license file + +Copyright +^^^^^^^^^ + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is in the :ref:`gnu_fdl`. \ No newline at end of file diff --git a/gcc/d/doc/general-public-license-3.rst b/gcc/d/doc/general-public-license-3.rst new file mode 100644 index 00000000000..becda773ca0 --- /dev/null +++ b/gcc/d/doc/general-public-license-3.rst @@ -0,0 +1,6 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. include:: ../../../doc/gpl-3.0.rst \ No newline at end of file diff --git a/gcc/d/doc/gnu-free-documentation-license.rst b/gcc/d/doc/gnu-free-documentation-license.rst new file mode 100644 index 00000000000..1de809b3636 --- /dev/null +++ b/gcc/d/doc/gnu-free-documentation-license.rst @@ -0,0 +1,6 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. include:: ../../../doc/gnu_free_documentation_license.rst \ No newline at end of file diff --git a/gcc/d/doc/index.rst b/gcc/d/doc/index.rst new file mode 100644 index 00000000000..700a4a8d885 --- /dev/null +++ b/gcc/d/doc/index.rst @@ -0,0 +1,22 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +The GNU D Compiler +================== + +This manual describes how to use :command:`gdc`, the GNU compiler for +the D programming language. This manual is specifically about +:command:`gdc`. For more information about the D programming +language in general, including language specifications and standard +package documentation, see https://dlang.org/. + +.. toctree:: + + copyright + invoking-gdc + general-public-license-3 + gnu-free-documentation-license + + indices-and-tables \ No newline at end of file diff --git a/gcc/d/doc/indices-and-tables.rst b/gcc/d/doc/indices-and-tables.rst new file mode 100644 index 00000000000..6c215a391d9 --- /dev/null +++ b/gcc/d/doc/indices-and-tables.rst @@ -0,0 +1 @@ +.. include:: ../../../doc/indices-and-tables.rst \ No newline at end of file diff --git a/gcc/d/doc/invoking-gdc.rst b/gcc/d/doc/invoking-gdc.rst new file mode 100644 index 00000000000..be477b82f07 --- /dev/null +++ b/gcc/d/doc/invoking-gdc.rst @@ -0,0 +1,48 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _invoking-gdc: + +Invoking gdc +------------ + +.. only:: man + + Synopsis + ^^^^^^^^ + + gdc [ :option:`-c` | :option:`-S` ] [ :option:`-g` ] [ :option:`-pg` ] + [ :option:`-O`:samp:`{level}` ] [ :option:`-W`:samp:`{warn}`...] + [ :option:`-I`:samp:`{dir}`...] [ :option:`-L`:samp:`{dir}`...] + [ :option:`-f`:samp:`{option}`...] [ :option:`-m`:samp:`{machine-option}`...] + [ :option:`-o` :samp:`{outfile}` ] [@ :samp:`{file}` ] :samp:`{infile}`... + + Only the most useful options are listed here; see below for the + remainder. + +Description +^^^^^^^^^^^ + +The :command:`gdc` command is the GNU compiler for the D language and +supports many of the same options as :command:`gcc`. See :ref:`gcc:option-summary`. +This manual only documents the options specific to :command:`gdc`. + +Options +^^^^^^^ + +.. toctree:: + :maxdepth: 2 + + invoking-gdc/input-and-output-files + invoking-gdc/runtime-options + invoking-gdc/options-for-directory-search + invoking-gdc/code-generation + invoking-gdc/warnings + invoking-gdc/options-for-linking + invoking-gdc/developer-options + +.. only:: man + + .. include:: copyright.rst \ No newline at end of file diff --git a/gcc/d/doc/invoking-gdc/code-generation.rst b/gcc/d/doc/invoking-gdc/code-generation.rst new file mode 100644 index 00000000000..178b6f98fe2 --- /dev/null +++ b/gcc/d/doc/invoking-gdc/code-generation.rst @@ -0,0 +1,170 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: options, code generation + +.. _code-generation: + +Code Generation +*************** + +In addition to the many :command:`gcc` options controlling code generation, +:command:`gdc` has several options specific to itself. + +.. option:: -H + + .. index:: -H + + Generates D interface files for all modules being compiled. The compiler + determines the output file based on the name of the input file, removes + any directory components and suffix, and applies the :samp:`.di` suffix. + +.. option:: -Hd dir + + .. index:: -Hd + + Same as :option:`-H`, but writes interface files to directory :samp:`{dir}`. + This option can be used with :option:`-Hf file` to independently set the + output file and directory path. + +.. option:: -Hf file + + .. index:: -Hf + + Same as :option:`-H` but writes interface files to :samp:`{file}`. This option can + be used with :option:`-Hd dir` to independently set the output file and + directory path. + +.. option:: -M + + .. index:: -M + + Output the module dependencies of all source files being compiled in a + format suitable for :command:`make`. The compiler outputs one + :command:`make` rule containing the object file name for that source file, + a colon, and the names of all imported files. + +.. option:: -MM + + .. index:: -MM + + Like :option:`-M` but does not mention imported modules from the D standard + library package directories. + +.. option:: -MF file + + .. index:: -MF + + When used with :option:`-M` or :option:`-MM`, specifies a :samp:`{file}` to write + the dependencies to. When used with the driver options :option:`-MD` or + :option:`-MMD`, :option:`-MF` overrides the default dependency output file. + +.. option:: -MG + + .. index:: -MG + + This option is for compatibility with :command:`gcc`, and is ignored by the + compiler. + +.. option:: -MP + + .. index:: -MP + + Outputs a phony target for each dependency other than the modules being + compiled, causing each to depend on nothing. + +.. option:: -MT target + + .. index:: -MT + + Change the :samp:`{target}` of the rule emitted by dependency generation + to be exactly the string you specify. If you want multiple targets, + you can specify them as a single argument to :option:`-MT`, or use + multiple :option:`-MT` options. + +.. option:: -MQ target + + .. index:: -MQ + + Same as :option:`-MT`, but it quotes any characters which are special to + :command:`make`. + +.. option:: -MD + + .. index:: -MD + + This option is equivalent to :option:`-M -MF file`. The driver + determines :samp:`{file}` by removing any directory components and suffix + from the input file, and then adding a :samp:`.deps` suffix. + +.. option:: -MMD + + .. index:: -MMD + + Like :option:`-MD` but does not mention imported modules from the D standard + library package directories. + +.. option:: -X + + .. index:: -X + + Output information describing the contents of all source files being + compiled in JSON format to a file. The driver determines :samp:`{file}` by + removing any directory components and suffix from the input file, and then + adding a :samp:`.json` suffix. + +.. option:: -Xf file + + .. index:: -Xf + + Same as :option:`-X`, but writes all JSON contents to the specified + :samp:`{file}`. + +.. option:: -fdoc + + .. index:: -fdoc + + Generates ``Ddoc`` documentation and writes it to a file. The compiler + determines :samp:`{file}` by removing any directory components and suffix + from the input file, and then adding a :samp:`.html` suffix. + +.. option:: -fdoc-dir=dir + + .. index:: -fdoc-dir + + Same as :option:`-fdoc`, but writes documentation to directory :samp:`{dir}`. + This option can be used with :option:`-fdoc-file=file` to + independently set the output file and directory path. + +.. option:: -fdoc-file=file + + .. index:: -fdoc-file + + Same as :option:`-fdoc`, but writes documentation to :samp:`{file}`. This + option can be used with :option:`-fdoc-dir=dir` to independently + set the output file and directory path. + +.. option:: -fdoc-inc=file + + .. index:: -fdoc-inc + + Specify :samp:`{file}` as a :samp:`{Ddoc}` macro file to be read. Multiple + :option:`-fdoc-inc` options can be used, and files are read and processed + in the same order. + +.. option:: -fdump-c++-spec={file} + + For D source files, generate corresponding C++ declarations in :samp:`{file}`. + +.. option:: -fdump-c++-spec-verbose + + In conjunction with :option:`-fdump-c++-spec=` above, add comments for ignored + declarations in the generated C++ header. + +.. option:: -fsave-mixins={file} + + Generates code expanded from D ``mixin`` statements and writes the + processed sources to :samp:`{file}`. This is useful to debug errors in compilation + and provides source for debuggers to show when requested. \ No newline at end of file diff --git a/gcc/d/doc/invoking-gdc/developer-options.rst b/gcc/d/doc/invoking-gdc/developer-options.rst new file mode 100644 index 00000000000..564ed36d6c0 --- /dev/null +++ b/gcc/d/doc/invoking-gdc/developer-options.rst @@ -0,0 +1,31 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: developer options, debug dump options, dump options + +.. _developer-options: + +Developer Options +***************** + +This section describes command-line options that are primarily of +interest to developers or language tooling. + +.. option:: -fdump-d-original + + .. index:: -fdump-d-original + + Output the internal front-end AST after the ``semantic3`` stage. + This option is only useful for debugging the GNU D compiler itself. + +.. option:: -v + + .. index:: -v + + Dump information about the compiler language processing stages as the source + program is being compiled. This includes listing all modules that are + processed through the ``parse``, ``semantic``, ``semantic2``, and + ``semantic3`` stages; all ``import`` modules and their file paths; + and all ``function`` bodies that are being compiled. \ No newline at end of file diff --git a/gcc/d/doc/invoking-gdc/input-and-output-files.rst b/gcc/d/doc/invoking-gdc/input-and-output-files.rst new file mode 100644 index 00000000000..a4bce6b9aba --- /dev/null +++ b/gcc/d/doc/invoking-gdc/input-and-output-files.rst @@ -0,0 +1,45 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: suffixes for D source, D source file suffixes + +.. _input-and-output-files: + +Input and Output files +********************** + +For any given input file, the file name suffix determines what kind of +compilation is done. The following kinds of input file names are supported: + +:samp:`{file}.d` + D source files. + +:samp:`{file}.dd` + Ddoc source files. + +:samp:`{file}.di` + D interface files. + +You can specify more than one input file on the :command:`gdc` command line, +each being compiled separately in the compilation process. If you specify a +``-o file`` option, all the input files are compiled together, +producing a single output file, named :samp:`{file}`. This is allowed even +when using ``-S`` or ``-c``. + +.. index:: D interface files. + +A D interface file contains only what an import of the module needs, +rather than the whole implementation of that module. They can be created +by :command:`gdc` from a D source file by using the ``-H`` option. +When the compiler resolves an import declaration, it searches for matching +:samp:`.di` files first, then for :samp:`.d`. + +.. index:: Ddoc source files. + +A Ddoc source file contains code in the D macro processor language. It is +primarily designed for use in producing user documentation from embedded +comments, with a slight affinity towards HTML generation. If a :samp:`.d` +source file starts with the string ``Ddoc`` then it is treated as general +purpose documentation, not as a D source file. \ No newline at end of file diff --git a/gcc/d/doc/invoking-gdc/options-for-directory-search.rst b/gcc/d/doc/invoking-gdc/options-for-directory-search.rst new file mode 100644 index 00000000000..934b22df5b0 --- /dev/null +++ b/gcc/d/doc/invoking-gdc/options-for-directory-search.rst @@ -0,0 +1,92 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: directory options, options, directory search, search path + +.. _directory-options: + +Options for Directory Search +**************************** + +These options specify directories to search for files, libraries, and +other parts of the compiler: + +.. option:: -Idir + + .. index:: -I + + Specify a directory to use when searching for imported modules at + compile time. Multiple :option:`-I` options can be used, and the + paths are searched in the same order. + +.. option:: -Jdir + + .. index:: -J + + Specify a directory to use when searching for files in string imports + at compile time. This switch is required in order to use + ``import(file)`` expressions. Multiple :option:`-J` options can be + used, and the paths are searched in the same order. + +.. option:: -Ldir + + .. index:: -L + + When linking, specify a library search directory, as with :command:`gcc`. + +.. option:: -Bdir + + .. index:: -B + + This option specifies where to find the executables, libraries, + source files, and data files of the compiler itself, as with :command:`gcc`. + +.. option:: -fmodule-file=module=spec + + .. index:: -fmodule-file + + This option manipulates file paths of imported modules, such that if an + imported module matches all or the leftmost part of :samp:`{module}`, the file + path in :samp:`{spec}` is used as the location to search for D sources. + This is used when the source file path and names are not the same as the + package and module hierarchy. Consider the following examples: + + .. code-block:: c++ + + gdc test.d -fmodule-file=A.B=foo.d -fmodule-file=C=bar + + This will tell the compiler to search in all import paths for the source + file :samp:`{foo.d}` when importing :samp:`{A.B}`, and the directory :samp:`{bar/}` + when importing :samp:`{C}`, as annotated in the following D code: + + .. code-block:: c++ + + module test; + import A.B; // Matches A.B, searches for foo.d + import C.D.E; // Matches C, searches for bar/D/E.d + import A.B.C; // No match, searches for A/B/C.d + +.. option:: -imultilib dir + + .. index:: -imultilib + + Use :samp:`{dir}` as a subdirectory of the gcc directory containing + target-specific D sources and interfaces. + +.. option:: -iprefix prefix + + .. index:: -iprefix + + Specify :samp:`{prefix}` as the prefix for the gcc directory containing + target-specific D sources and interfaces. If the :samp:`{prefix}` represents + a directory, you should include the final ``'/'``. + +.. option:: -nostdinc + + .. index:: -nostdinc + + Do not search the standard system directories for D source and interface + files. Only the directories that have been specified with :option:`-I` options + (and the directory of the current file, if appropriate) are searched. \ No newline at end of file diff --git a/gcc/d/doc/invoking-gdc/options-for-linking.rst b/gcc/d/doc/invoking-gdc/options-for-linking.rst new file mode 100644 index 00000000000..dc64fcd206a --- /dev/null +++ b/gcc/d/doc/invoking-gdc/options-for-linking.rst @@ -0,0 +1,59 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: options, linking, linking, static + +.. _linking: + +Options for Linking +******************* + +These options come into play when the compiler links object files into an +executable output file. They are meaningless if the compiler is not doing +a link step. + +.. option:: -defaultlib=libname + + .. index:: -defaultlib= + + Specify the library to use instead of libphobos when linking. Options + specifying the linkage of libphobos, such as :option:`-static-libphobos` + or :option:`-shared-libphobos`, are ignored. + +.. option:: -debuglib=libname + + .. index:: -debuglib= + + Specify the debug library to use instead of libphobos when linking. + This option has no effect unless the :option:`-g` option was also given + on the command line. Options specifying the linkage of libphobos, such + as :option:`-static-libphobos` or :option:`-shared-libphobos`, are ignored. + +.. option:: -nophoboslib + + .. index:: -nophoboslib + + Do not use the Phobos or D runtime library when linking. Options specifying + the linkage of libphobos, such as :option:`-static-libphobos` or + :option:`-shared-libphobos`, are ignored. The standard system libraries are + used normally, unless :option:`-nostdlib` or :option:`-nodefaultlibs` is used. + +.. option:: -shared-libphobos + + .. index:: -shared-libphobos + + On systems that provide :samp:`libgphobos` and :samp:`libgdruntime` as a + shared and a static library, this option forces the use of the shared + version. If no shared version was built when the compiler was configured, + this option has no effect. + +.. option:: -static-libphobos + + .. index:: -static-libphobos + + On systems that provide :samp:`libgphobos` and :samp:`libgdruntime` as a + shared and a static library, this option forces the use of the static + version. If no static version was built when the compiler was configured, + this option has no effect. \ No newline at end of file diff --git a/gcc/d/doc/invoking-gdc/runtime-options.rst b/gcc/d/doc/invoking-gdc/runtime-options.rst new file mode 100644 index 00000000000..fda87c2b96e --- /dev/null +++ b/gcc/d/doc/invoking-gdc/runtime-options.rst @@ -0,0 +1,314 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: options, runtime + +.. _runtime-options: + +Runtime Options +*************** + +These options affect the runtime behavior of programs compiled with +:command:`gdc`. + +.. option:: -fall-instantiations + + .. index:: -fall-instantiations, -fno-all-instantiations + + Generate code for all template instantiations. The default template emission + strategy is to not generate code for declarations that were either + instantiated speculatively, such as from ``__traits(compiles, ...)``, or + that come from an imported module not being compiled. + +.. option:: -fno-assert + + .. index:: -fassert, -fno-assert + + Turn off code generation for ``assert`` contracts. + +.. option:: -fno-bounds-check + + .. index:: -fbounds-check, -fno-bounds-check + + Turns off array bounds checking for all functions, which can improve + performance for code that uses arrays extensively. Note that this + can result in unpredictable behavior if the code in question actually + does violate array bounds constraints. It is safe to use this option + if you are sure that your code never throws a ``RangeError``. + +.. option:: -fbounds-check=value + + .. index:: -fbounds-check= + + An alternative to :option:`-fbounds-check` that allows more control + as to where bounds checking is turned on or off. The following values + are supported: + + :samp:`on` + Turns on array bounds checking for all functions. + + :samp:`safeonly` + Turns on array bounds checking only for ``@safe`` functions. + + :samp:`off` + Turns off array bounds checking completely. + +.. option:: -fno-builtin + + .. index:: -fbuiltin, -fno-builtin + + Don't recognize built-in functions unless they begin with the prefix + :samp:`__builtin_`. By default, the compiler will recognize when a + function in the ``core.stdc`` package is a built-in function. + +.. option:: -fcheckaction + + This option controls what code is generated on an assertion, bounds check, or + final switch failure. The following values are supported: + + :samp:`context` + Throw an ``AssertError`` with extra context information. + + :samp:`halt` + Halt the program execution. + + :samp:`throw` + Throw an ``AssertError`` (the default). + +.. option:: -fdebug=value + + .. index:: -fno-debug + + Turn on compilation of conditional ``debug`` code into the program. + The :option:`-fdebug` option itself sets the debug level to ``1``, + while :option:`-fdebug=` enables ``debug`` code that are identified + by any of the following values: + + :samp:`level` + Sets the debug level to :samp:`{level}`, any ``debug`` code <= :samp:`{level}` + is compiled into the program. + + :samp:`ident` + Turns on compilation of any ``debug`` code identified by :samp:`{ident}`. + +.. option:: -fno-druntime + + .. index:: -fdruntime, -fno-druntime + + Implements https://dlang.org/spec/betterc.html. Assumes that + compilation targets an environment without a D runtime library. + + This is equivalent to compiling with the following options: + + .. code-block:: c++ + + gdc -nophoboslib -fno-exceptions -fno-moduleinfo -fno-rtti + +.. option:: -fextern-std=standard + + Sets the C++ name mangling compatibility to the version identified by + :samp:`{standard}`. The following values are supported: + + :samp:`c++98`, :samp:`c++03` + Sets ``__traits(getTargetInfo, "cppStd")`` to ``199711``. + + :samp:`c++11` + Sets ``__traits(getTargetInfo, "cppStd")`` to ``201103``. + + :samp:`c++14` + Sets ``__traits(getTargetInfo, "cppStd")`` to ``201402``. + + :samp:`c++17` + Sets ``__traits(getTargetInfo, "cppStd")`` to ``201703``. + This is the default. + + :samp:`c++20` + Sets ``__traits(getTargetInfo, "cppStd")`` to ``202002``. + +.. option:: -fno-invariants + + .. index:: -finvariants, -fno-invariants + + Turns off code generation for class ``invariant`` contracts. + +.. option:: -fmain + + Generates a default ``main()`` function when compiling. This is useful when + unittesting a library, as it enables running the unittests in a library without + having to manually define an entry-point function. This option does nothing + when ``main`` is already defined in user code. + +.. option:: -fno-moduleinfo + + Turns off generation of the ``ModuleInfo`` and related functions + that would become unreferenced without it, which may allow linking + to programs not written in D. Functions that are not be generated + include module constructors and destructors (``static this`` and + ``static ~this``), ``unittest`` code, and ``DSO`` registry + functions for dynamically linked code. + +.. option:: -fonly=filename + + .. index:: -fonly + + Tells the compiler to parse and run semantic analysis on all modules + on the command line, but only generate code for the module specified + by :samp:`{filename}`. + +.. option:: -fno-postconditions + + .. index:: -fpostconditions, -fno-postconditions + + Turns off code generation for postcondition ``out`` contracts. + +.. option:: -fno-preconditions + + .. index:: -fpreconditions, -fno-preconditions + + Turns off code generation for precondition ``in`` contracts. + +.. option:: -fpreview=id + + .. index:: -fpreview + + Turns on an upcoming D language change identified by :samp:`{id}`. The following + values are supported: + + :samp:`all` + Turns on all upcoming D language features. + + :samp:`dip1000` + Implements https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md + (Scoped pointers). + + :samp:`dip1008` + Implements https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1008.md + (Allow exceptions in ``@nogc`` code). + + :samp:`dip1021` + Implements https://github.com/dlang/DIPs/blob/master/DIPs/accepted/DIP1021.md + (Mutable function arguments). + + :samp:`dip25` + Implements https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md + (Sealed references). + + :samp:`dtorfields` + Turns on generation for destructing fields of partially constructed objects. + + :samp:`fieldwise` + Turns on generation of struct equality to use field-wise comparisons. + + :samp:`fixaliasthis` + Implements new lookup rules that check the current scope for ``alias this`` + before searching in upper scopes. + + :samp:`fiximmutableconv` + Disallows unsound immutable conversions that were formerly incorrectly + permitted. + + :samp:`in` + Implements ``in`` parameters to mean ``scope const [ref]`` and accepts + rvalues. + + :samp:`inclusiveincontracts` + Implements ``in`` contracts of overridden methods to be a superset of parent + contract. + + :samp:`intpromote` + Implements C-style integral promotion for unary ``+``, ``-`` and ``~`` + expressions. + + :samp:`nosharedaccess` + Turns off and disallows all access to shared memory objects. + + :samp:`rvaluerefparam` + Implements rvalue arguments to ``ref`` parameters. + + :samp:`systemvariables` + Disables access to variables marked ``@system`` from ``@safe`` code. + +.. option:: -frelease + + .. index:: -fno-release + + Turns on compiling in release mode, which means not emitting runtime + checks for contracts and asserts. Array bounds checking is not done + for ``@system`` and ``@trusted`` functions, and assertion + failures are undefined behavior. + + This is equivalent to compiling with the following options: + + .. code-block:: c++ + + gdc -fno-assert -fbounds-check=safe -fno-invariants \ + -fno-postconditions -fno-preconditions -fno-switch-errors + +.. option:: -frevert= + + .. index:: -frevert + + Turns off a D language feature identified by :samp:`{id}`. The following values + are supported: + + :samp:`all` + Turns off all revertable D language features. + + :samp:`dip25` + Reverts https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md + (Sealed references). + + :samp:`dtorfields` + Turns off generation for destructing fields of partially constructed objects. + + :samp:`markdown` + Turns off Markdown replacements in Ddoc comments. + +.. option:: -fno-rtti + + .. index:: -frtti, -fno-rtti + + Turns off generation of run-time type information for all user defined types. + Any code that uses features of the language that require access to this + information will result in an error. + +.. option:: -fno-switch-errors + + .. index:: -fswitch-errors, -fno-switch-errors + + This option controls what code is generated when no case is matched + in a ``final switch`` statement. The default run time behavior + is to throw a ``SwitchError``. Turning off :option:`-fswitch-errors` + means that instead the execution of the program is immediately halted. + +.. option:: -funittest + + .. index:: -funittest, -fno-unittest + + Turns on compilation of ``unittest`` code, and turns on the + ``version(unittest)`` identifier. This implies :option:`-fassert`. + +.. option:: -fversion=value + + .. index:: -fversion + + Turns on compilation of conditional ``version`` code into the program + identified by any of the following values: + + :samp:`level` + Sets the version level to :samp:`{level}`, any ``version`` code >= :samp:`{level}` + is compiled into the program. + + :samp:`ident` + Turns on compilation of ``version`` code identified by :samp:`{ident}`. + +.. option:: -fno-weak-templates + + .. index:: -fweak-templates, -fno-weak-templates + + Turns off emission of declarations that can be defined in multiple objects as + weak symbols. The default is to emit all public symbols as weak, unless the + target lacks support for weak symbols. Disabling this option means that common + symbols are instead put in COMDAT or become private. \ No newline at end of file diff --git a/gcc/d/doc/invoking-gdc/warnings.rst b/gcc/d/doc/invoking-gdc/warnings.rst new file mode 100644 index 00000000000..c9ed52e7630 --- /dev/null +++ b/gcc/d/doc/invoking-gdc/warnings.rst @@ -0,0 +1,148 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: options to control warnings, warning messages, messages, warning, suppressing warnings + +.. _warnings: + +Warnings +******** + +Warnings are diagnostic messages that report constructions that +are not inherently erroneous but that are risky or suggest there +is likely to be a bug in the program. Unless :option:`-Werror` is +specified, they do not prevent compilation of the program. + +.. option:: -Wall + + .. index:: -Wall, -Wno-all + + Turns on all warnings messages. Warnings are not a defined part of + the D language, and all constructs for which this may generate a + warning message are valid code. + +.. option:: -Walloca + + .. index:: -Walloca + + This option warns on all uses of "alloca" in the source. + +.. option:: -Walloca-larger-than=n + + .. index:: -Walloca-larger-than, -Wno-alloca-larger-than + + Warn on unbounded uses of alloca, and on bounded uses of alloca + whose bound can be larger than :samp:`{n}` bytes. + :option:`-Wno-alloca-larger-than` disables + :option:`-Walloca-larger-than` warning and is equivalent to + :option:`-Walloca-larger-than=SIZE_MAX` or larger. + +.. option:: -Wcast-result + + .. index:: -Wcast-result, -Wno-cast-result + + Warn about casts that will produce a null or zero result. Currently + this is only done for casting between an imaginary and non-imaginary + data type, or casting between a D and C++ class. + +.. option:: -Wno-deprecated + + .. index:: -Wdeprecated, -Wno-deprecated + + Do not warn about usage of deprecated features and symbols with + ``deprecated`` attributes. + +.. option:: -Werror + + .. index:: -Werror, -Wno-error + + Turns all warnings into errors. + +.. option:: -Wspeculative + + .. index:: -Wspeculative, -Wno-speculative + + List all error messages from speculative compiles, such as + ``__traits(compiles, ...)``. This option does not report + messages as warnings, and these messages therefore never become + errors when the :option:`-Werror` option is also used. + +.. option:: -Wtemplates + + .. index:: -Wtemplates, -Wno-templates + + Warn when a template instantiation is encountered. Some coding + rules disallow templates, and this may be used to enforce that rule. + +.. option:: -Wunknown-pragmas + + .. index:: -Wunknown-pragmas, -Wno-unknown-pragmas + + Warn when a ``pragma()`` is encountered that is not understood by + :command:`gdc`. This differs from :option:`-fignore-unknown-pragmas` + where a pragma that is part of the D language, but not implemented by + the compiler, won't get reported. + +.. option:: -Wno-varargs + + .. index:: Wvarargs, Wno-varargs + + Do not warn upon questionable usage of the macros used to handle variable + arguments like ``va_start``. + +.. option:: -fignore-unknown-pragmas + + .. index:: -fignore-unknown-pragmas, -fno-ignore-unknown-pragmas + + Turns off errors for unsupported pragmas. + +.. option:: -fmax-errors=n + + .. index:: -fmax-errors + + Limits the maximum number of error messages to :samp:`{n}`, at which point + :command:`gdc` bails out rather than attempting to continue processing the + source code. If :samp:`{n}` is 0 (the default), there is no limit on the + number of error messages produced. + +.. option:: -fsyntax-only + + .. index:: -fsyntax-only, -fno-syntax-only + + Check the code for syntax errors, but do not actually compile it. This + can be used in conjunction with :option:`-fdoc` or :option:`-H` to generate + files for each module present on the command-line, but no other output + file. + +.. option:: -ftransition=id + + .. index:: -ftransition + + Report additional information about D language changes identified by + :samp:`{id}`. The following values are supported: + + :samp:`all` + List information on all D language transitions. + + :samp:`complex` + List all usages of complex or imaginary types. + + :samp:`field` + List all non-mutable fields which occupy an object instance. + + :samp:`in` + List all usages of ``in`` on parameter. + + :samp:`nogc` + List all hidden GC allocations. + + :samp:`templates` + List statistics on template instantiations. + + :samp:`tls` + List all variables going into thread local storage. + + :samp:`vmarkdown` + List instances of Markdown replacements in Ddoc. \ No newline at end of file diff --git a/gcc/doc/cpp/character-sets.rst b/gcc/doc/cpp/character-sets.rst new file mode 100644 index 00000000000..f4b6e05515c --- /dev/null +++ b/gcc/doc/cpp/character-sets.rst @@ -0,0 +1,56 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _character-sets: + +Character sets +************** + +Source code character set processing in C and related languages is +rather complicated. The C standard discusses two character sets, but +there are really at least four. + +The files input to CPP might be in any character set at all. CPP's +very first action, before it even looks for line boundaries, is to +convert the file into the character set it uses for internal +processing. That set is what the C standard calls the :dfn:`source` +character set. It must be isomorphic with ISO 10646, also known as +Unicode. CPP uses the UTF-8 encoding of Unicode. + +The character sets of the input files are specified using the +:option:`-finput-charset=` option. + +All preprocessing work (the subject of the rest of this manual) is +carried out in the source character set. If you request textual +output from the preprocessor with the :option:`-E` option, it will be +in UTF-8. + +After preprocessing is complete, string and character constants are +converted again, into the :dfn:`execution` character set. This +character set is under control of the user; the default is UTF-8, +matching the source character set. Wide string and character +constants have their own character set, which is not called out +specifically in the standard. Again, it is under control of the user. +The default is UTF-16 or UTF-32, whichever fits in the target's +``wchar_t`` type, in the target machine's byte +order [#f1]_. + +Octal and hexadecimal escape sequences do not undergo +conversion; ``'\x12'`` has the value 0x12 regardless of the currently +selected execution character set. All other escapes are replaced by +the character in the source character set that they represent, then +converted to the execution character set, just like unescaped +characters. + +In identifiers, characters outside the ASCII range can be specified +with the :samp:`\\u` and :samp:`\\U` escapes or used directly in the input +encoding. If strict ISO C90 conformance is specified with an option +such as :option:`-std=c90`, or :option:`-fno-extended-identifiers` is +used, then those constructs are not permitted in identifiers. + +.. [#f1] UTF-16 does not meet the requirements of the C + standard for a wide character set, but the choice of 16-bit + ``wchar_t`` is enshrined in some system ABIs so we cannot fix + this. \ No newline at end of file diff --git a/gcc/doc/cpp/conditional-syntax.rst b/gcc/doc/cpp/conditional-syntax.rst new file mode 100644 index 00000000000..1dec2ac6f4b --- /dev/null +++ b/gcc/doc/cpp/conditional-syntax.rst @@ -0,0 +1,411 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: #if + +.. _conditional-syntax: + +Conditional Syntax +****************** + +A conditional in the C preprocessor begins with a :dfn:`conditional +directive`: :samp:`#if`, :samp:`#ifdef` or :samp:`#ifndef`. + +.. toctree:: + :maxdepth: 2 + + +.. index:: #ifdef, #endif + +.. _ifdef: + +Ifdef +^^^^^ + +The simplest sort of conditional is + +.. code-block:: c++ + + #ifdef MACRO + + controlled text + + #endif /* MACRO */ + +.. index:: conditional group + +This block is called a :dfn:`conditional group`. :samp:`{controlled text}` +will be included in the output of the preprocessor if and only if +:samp:`{MACRO}` is defined. We say that the conditional :dfn:`succeeds` if +:samp:`{MACRO}` is defined, :dfn:`fails` if it is not. + +The :samp:`{controlled text}` inside of a conditional can include +preprocessing directives. They are executed only if the conditional +succeeds. You can nest conditional groups inside other conditional +groups, but they must be completely nested. In other words, +:samp:`#endif` always matches the nearest :samp:`#ifdef` (or +:samp:`#ifndef`, or :samp:`#if`). Also, you cannot start a conditional +group in one file and end it in another. + +Even if a conditional fails, the :samp:`{controlled text}` inside it is +still run through initial transformations and tokenization. Therefore, +it must all be lexically valid C. Normally the only way this matters is +that all comments and string literals inside a failing conditional group +must still be properly ended. + +The comment following the :samp:`#endif` is not required, but it is a +good practice if there is a lot of :samp:`{controlled text}`, because it +helps people match the :samp:`#endif` to the corresponding :samp:`#ifdef`. +Older programs sometimes put :samp:`{MACRO}` directly after the +:samp:`#endif` without enclosing it in a comment. This is invalid code +according to the C standard. CPP accepts it with a warning. It +never affects which :samp:`#ifndef` the :samp:`#endif` matches. + +.. index:: #ifndef + +Sometimes you wish to use some code if a macro is *not* defined. +You can do this by writing :samp:`#ifndef` instead of :samp:`#ifdef`. +One common use of :samp:`#ifndef` is to include code only the first +time a header file is included. See :ref:`once-only-headers`. + +Macro definitions can vary between compilations for several reasons. +Here are some samples. + +* Some macros are predefined on each kind of machine + (see :ref:`system-specific-predefined-macros`). This allows you to provide + code specially tuned for a particular machine. + +* System header files define more macros, associated with the features + they implement. You can test these macros with conditionals to avoid + using a system feature on a machine where it is not implemented. + +* Macros can be defined or undefined with the :option:`-D` and :option:`-U` + command-line options when you compile the program. You can arrange to + compile the same source file into two different programs by choosing a + macro name to specify which program you want, writing conditionals to + test whether or how this macro is defined, and then controlling the + state of the macro with command-line options, perhaps set in the + Makefile. See :ref:`invocation`. + +* Your program might have a special header file (often called + :samp:`config.h`) that is adjusted when the program is compiled. It can + define or not define macros depending on the features of the system and + the desired capabilities of the program. The adjustment can be + automated by a tool such as :command:`autoconf`, or done by hand. + +.. _if: + +If +^^ + +The :samp:`#if` directive allows you to test the value of an arithmetic +expression, rather than the mere existence of one macro. Its syntax is + +.. code-block:: c++ + + #if expression + + controlled text + + #endif /* expression */ + +:samp:`{expression}` is a C expression of integer type, subject to stringent +restrictions. It may contain + +* Integer constants. + +* Character constants, which are interpreted as they would be in normal + code. + +* Arithmetic operators for addition, subtraction, multiplication, + division, bitwise operations, shifts, comparisons, and logical + operations (``&&`` and ``||``). The latter two obey the usual + short-circuiting rules of standard C. + +* Macros. All macros in the expression are expanded before actual + computation of the expression's value begins. + +* Uses of the ``defined`` operator, which lets you check whether macros + are defined in the middle of an :samp:`#if`. + +* Identifiers that are not macros, which are all considered to be the + number zero. This allows you to write ``#if MACRO`` instead of + ``#ifdef MACRO``, if you know that MACRO, when defined, will + always have a nonzero value. Function-like macros used without their + function call parentheses are also treated as zero. + + In some contexts this shortcut is undesirable. The :option:`-Wundef` + option causes GCC to warn whenever it encounters an identifier which is + not a macro in an :samp:`#if`. + +The preprocessor does not know anything about types in the language. +Therefore, ``sizeof`` operators are not recognized in :samp:`#if`, and +neither are ``enum`` constants. They will be taken as identifiers +which are not macros, and replaced by zero. In the case of +``sizeof``, this is likely to cause the expression to be invalid. + +The preprocessor calculates the value of :samp:`{expression}`. It carries +out all calculations in the widest integer type known to the compiler; +on most machines supported by GCC this is 64 bits. This is not the same +rule as the compiler uses to calculate the value of a constant +expression, and may give different results in some cases. If the value +comes out to be nonzero, the :samp:`#if` succeeds and the :samp:`{controlled +text}` is included; otherwise it is skipped. + +.. index:: defined + +.. _defined: + +Defined +^^^^^^^ + +The special operator ``defined`` is used in :samp:`#if` and +:samp:`#elif` expressions to test whether a certain name is defined as a +macro. ``defined name`` and ``defined (name)`` are +both expressions whose value is 1 if :samp:`{name}` is defined as a macro at +the current point in the program, and 0 otherwise. Thus, ``#if +defined MACRO`` is precisely equivalent to ``#ifdef MACRO``. + +``defined`` is useful when you wish to test more than one macro for +existence at once. For example, + +.. code-block:: c++ + + #if defined (__vax__) || defined (__ns16000__) + +would succeed if either of the names ``__vax__`` or +``__ns16000__`` is defined as a macro. + +Conditionals written like this: + +.. code-block:: c++ + + #if defined BUFSIZE && BUFSIZE >= 1024 + +can generally be simplified to just ``#if BUFSIZE >= 1024``, +since if ``BUFSIZE`` is not defined, it will be interpreted as having +the value zero. + +If the ``defined`` operator appears as a result of a macro expansion, +the C standard says the behavior is undefined. GNU cpp treats it as a +genuine ``defined`` operator and evaluates it normally. It will warn +wherever your code uses this feature if you use the command-line option +:option:`-Wpedantic`, since other compilers may handle it differently. The +warning is also enabled by :option:`-Wextra`, and can also be enabled +individually with :option:`-Wexpansion-to-defined`. + +.. index:: #else + +.. _else: + +Else +^^^^ + +The :samp:`#else` directive can be added to a conditional to provide +alternative text to be used if the condition fails. This is what it +looks like: + +.. code-block:: c++ + + #if expression + text-if-true + #else /* Not expression */ + text-if-false + #endif /* Not expression */ + +If :samp:`{expression}` is nonzero, the :samp:`{text-if-true}` is included and +the :samp:`{text-if-false}` is skipped. If :samp:`{expression}` is zero, the +opposite happens. + +You can use :samp:`#else` with :samp:`#ifdef` and :samp:`#ifndef`, too. + +.. index:: #elif + +.. _elif: + +Elif +^^^^ + +One common case of nested conditionals is used to check for more than two +possible alternatives. For example, you might have + +.. code-block:: c++ + + #if X == 1 + ... + #else /* X != 1 */ + #if X == 2 + ... + #else /* X != 2 */ + ... + #endif /* X != 2 */ + #endif /* X != 1 */ + +Another conditional directive, :samp:`#elif`, allows this to be +abbreviated as follows: + +.. code-block:: c++ + + #if X == 1 + ... + #elif X == 2 + ... + #else /* X != 2 and X != 1*/ + ... + #endif /* X != 2 and X != 1*/ + +:samp:`#elif` stands for 'else if'. Like :samp:`#else`, it goes in the +middle of a conditional group and subdivides it; it does not require a +matching :samp:`#endif` of its own. Like :samp:`#if`, the :samp:`#elif` +directive includes an expression to be tested. The text following the +:samp:`#elif` is processed only if the original :samp:`#if`-condition +failed and the :samp:`#elif` condition succeeds. + +More than one :samp:`#elif` can go in the same conditional group. Then +the text after each :samp:`#elif` is processed only if the :samp:`#elif` +condition succeeds after the original :samp:`#if` and all previous +:samp:`#elif` directives within it have failed. + +:samp:`#else` is allowed after any number of :samp:`#elif` directives, but +:samp:`#elif` may not follow :samp:`#else`. + +.. index:: __has_attribute + +__has_attribute +^^^^^^^^^^^^^^^ + +The special operator ``__has_attribute (operand)`` may be used +in :samp:`#if` and :samp:`#elif` expressions to test whether the attribute +referenced by its :samp:`{operand}` is recognized by GCC. Using the operator +in other contexts is not valid. In C code, if compiling for strict +conformance to standards before C2x, :samp:`{operand}` must be +a valid identifier. Otherwise, :samp:`{operand}` may be optionally +introduced by the ``attribute-scope::`` prefix. +The :samp:`{attribute-scope}` prefix identifies the 'namespace' within +which the attribute is recognized. The scope of GCC attributes is +:samp:`gnu` or :samp:`__gnu__`. The ``__has_attribute`` operator by +itself, without any :samp:`{operand}` or parentheses, acts as a predefined +macro so that support for it can be tested in portable code. Thus, +the recommended use of the operator is as follows: + +.. code-block:: c++ + + #if defined __has_attribute + # if __has_attribute (nonnull) + # define ATTR_NONNULL __attribute__ ((nonnull)) + # endif + #endif + +The first :samp:`#if` test succeeds only when the operator is supported +by the version of GCC (or another compiler) being used. Only when that +test succeeds is it valid to use ``__has_attribute`` as a preprocessor +operator. As a result, combining the two tests into a single expression as +shown below would only be valid with a compiler that supports the operator +but not with others that don't. + +.. code-block:: c++ + + #if defined __has_attribute && __has_attribute (nonnull) /* not portable */ + ... + #endif + +.. index:: __has_cpp_attribute + +__has_cpp_attribute +^^^^^^^^^^^^^^^^^^^ + +The special operator ``__has_cpp_attribute (operand)`` may be used +in :samp:`#if` and :samp:`#elif` expressions in C++ code to test whether +the attribute referenced by its :samp:`{operand}` is recognized by GCC. +``__has_cpp_attribute (operand)`` is equivalent to +``__has_attribute (operand)`` except that when :samp:`{operand}` +designates a supported standard attribute it evaluates to an integer +constant of the form ``YYYYMM`` indicating the year and month when +the attribute was first introduced into the C++ standard. For additional +information including the dates of the introduction of current standard +attributes, see `SD-6: SG10 Feature Test Recommendations `_. + +.. index:: __has_c_attribute + +__has_c_attribute +^^^^^^^^^^^^^^^^^ + +The special operator ``__has_c_attribute (operand)`` may be +used in :samp:`#if` and :samp:`#elif` expressions in C code to test +whether the attribute referenced by its :samp:`{operand}` is recognized by +GCC in attributes using the :samp:`[[]]` syntax. GNU attributes must +be specified with the scope :samp:`gnu` or :samp:`__gnu__` with +``__has_c_attribute``. When :samp:`{operand}` designates a supported +standard attribute it evaluates to an integer constant of the form +``YYYYMM`` indicating the year and month when the attribute was +first introduced into the C standard, or when the syntax of operands +to the attribute was extended in the C standard. + +.. index:: __has_builtin + +__has_builtin +^^^^^^^^^^^^^ + +The special operator ``__has_builtin (operand)`` may be used in +constant integer contexts and in preprocessor :samp:`#if` and :samp:`#elif` +expressions to test whether the symbol named by its :samp:`{operand}` is +recognized as a built-in function by GCC in the current language and +conformance mode. It evaluates to a constant integer with a nonzero +value if the argument refers to such a function, and to zero otherwise. +The operator may also be used in preprocessor :samp:`#if` and :samp:`#elif` +expressions. The ``__has_builtin`` operator by itself, without any +:samp:`{operand}` or parentheses, acts as a predefined macro so that support +for it can be tested in portable code. Thus, the recommended use of +the operator is as follows: + +.. code-block:: c++ + + #if defined __has_builtin + # if __has_builtin (__builtin_object_size) + # define builtin_object_size(ptr) __builtin_object_size (ptr, 2) + # endif + #endif + #ifndef builtin_object_size + # define builtin_object_size(ptr) ((size_t)-1) + #endif + +.. index:: __has_include + +__has_include +^^^^^^^^^^^^^ + +The special operator ``__has_include (operand)`` may be used in +:samp:`#if` and :samp:`#elif` expressions to test whether the header referenced +by its :samp:`{operand}` can be included using the :samp:`#include` directive. Using +the operator in other contexts is not valid. The :samp:`{operand}` takes +the same form as the file in the :samp:`#include` directive (see :ref:`include-syntax`) and evaluates to a nonzero value if the header can be included and +to zero otherwise. Note that that the ability to include a header doesn't +imply that the header doesn't contain invalid constructs or :samp:`#error` +directives that would cause the preprocessor to fail. + +The ``__has_include`` operator by itself, without any :samp:`{operand}` or +parentheses, acts as a predefined macro so that support for it can be tested +in portable code. Thus, the recommended use of the operator is as follows: + +.. code-block:: c++ + + #if defined __has_include + # if __has_include () + # include + # endif + #endif + +The first :samp:`#if` test succeeds only when the operator is supported +by the version of GCC (or another compiler) being used. Only when that +test succeeds is it valid to use ``__has_include`` as a preprocessor +operator. As a result, combining the two tests into a single expression +as shown below would only be valid with a compiler that supports the operator +but not with others that don't. + +.. code-block:: c++ + + #if defined __has_include && __has_include ("header.h") /* not portable */ + ... + #endif \ No newline at end of file diff --git a/gcc/doc/cpp/conditional-uses.rst b/gcc/doc/cpp/conditional-uses.rst new file mode 100644 index 00000000000..59555a5828d --- /dev/null +++ b/gcc/doc/cpp/conditional-uses.rst @@ -0,0 +1,32 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _conditional-uses: + +Conditional Uses +**************** + +There are three general reasons to use a conditional. + +* A program may need to use different code depending on the machine or + operating system it is to run on. In some cases the code for one + operating system may be erroneous on another operating system; for + example, it might refer to data types or constants that do not exist on + the other system. When this happens, it is not enough to avoid + executing the invalid code. Its mere presence will cause the compiler + to reject the program. With a preprocessing conditional, the offending + code can be effectively excised from the program when it is not valid. + +* You may want to be able to compile the same source file into two + different programs. One version might make frequent time-consuming + consistency checks on its intermediate data, or print the values of + those data for debugging, and the other not. + +* A conditional whose condition is always false is one way to exclude code + from the program but keep it as a sort of comment for future reference. + +Simple programs that do not need system-specific logic or complex +debugging hooks generally will not need to use preprocessing +conditionals. \ No newline at end of file diff --git a/gcc/doc/cpp/conditionals.rst b/gcc/doc/cpp/conditionals.rst new file mode 100644 index 00000000000..381a6124da4 --- /dev/null +++ b/gcc/doc/cpp/conditionals.rst @@ -0,0 +1,44 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: conditionals + +.. _conditionals: + +Conditionals +------------ + +A :dfn:`conditional` is a directive that instructs the preprocessor to +select whether or not to include a chunk of code in the final token +stream passed to the compiler. Preprocessor conditionals can test +arithmetic expressions, or whether a name is defined as a macro, or both +simultaneously using the special ``defined`` operator. + +A conditional in the C preprocessor resembles in some ways an ``if`` +statement in C, but it is important to understand the difference between +them. The condition in an ``if`` statement is tested during the +execution of your program. Its purpose is to allow your program to +behave differently from run to run, depending on the data it is +operating on. The condition in a preprocessing conditional directive is +tested when your program is compiled. Its purpose is to allow different +code to be included in the program depending on the situation at the +time of compilation. + +However, the distinction is becoming less clear. Modern compilers often +do test ``if`` statements when a program is compiled, if their +conditions are known not to vary at run time, and eliminate code which +can never be executed. If you can count on your compiler to do this, +you may find that your program is more readable if you use ``if`` +statements with constant conditions (perhaps determined by macros). Of +course, you can only use this to exclude code, not type definitions or +other preprocessing directives, and you can only do it if the code +remains syntactically valid when it is not to be used. + +.. toctree:: + :maxdepth: 2 + + conditional-uses + conditional-syntax + deleted-code \ No newline at end of file diff --git a/gcc/doc/cpp/conf.py b/gcc/doc/cpp/conf.py new file mode 100644 index 00000000000..29d3aed4558 --- /dev/null +++ b/gcc/doc/cpp/conf.py @@ -0,0 +1,30 @@ +# Configuration file for the Sphinx documentation builder. + +import sys +sys.path.append('../../..//doc') + +from baseconf import * + +name = 'cpp' +project = 'The C Preprocessor' +copyright = '1987-2022 Free Software Foundation, Inc.' +authors = 'Richard M. Stallman, Zachary Weinberg' + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +latex_documents = [ + ('index', f'{name}.tex', project, authors, 'manual'), +] + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('invocation', name, project, [authors], 1), +] + +texinfo_documents = [ + ('index', name, project, authors, None, None, None, True) +] + +set_common(name, globals()) \ No newline at end of file diff --git a/gcc/doc/cpp/copyright.rst b/gcc/doc/cpp/copyright.rst new file mode 100644 index 00000000000..fa61190ddf7 --- /dev/null +++ b/gcc/doc/cpp/copyright.rst @@ -0,0 +1,24 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the GPL license file + +Copyright +^^^^^^^^^ + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, the Front-Cover Texts being (a) (see below), and +with the Back-Cover Texts being (b) (see below). +A copy of the license is included in the :ref:`gnu_fdl`. + +(a) The FSF's Front-Cover Text is: + + A GNU Manual + +(b) The FSF's Back-Cover Text is: + + You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. \ No newline at end of file diff --git a/gcc/doc/cpp/deleted-code.rst b/gcc/doc/cpp/deleted-code.rst new file mode 100644 index 00000000000..758e0c1c0a3 --- /dev/null +++ b/gcc/doc/cpp/deleted-code.rst @@ -0,0 +1,34 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: commenting out code + +.. _deleted-code: + +Deleted Code +************ + +If you replace or delete a part of the program but want to keep the old +code around for future reference, you often cannot simply comment it +out. Block comments do not nest, so the first comment inside the old +code will end the commenting-out. The probable result is a flood of +syntax errors. + +One way to avoid this problem is to use an always-false conditional +instead. For instance, put ``#if 0`` before the deleted code and +``#endif`` after it. This works even if the code being turned +off contains conditionals, but they must be entire conditionals +(balanced :samp:`#if` and :samp:`#endif`). + +Some people use ``#ifdef notdef`` instead. This is risky, because +``notdef`` might be accidentally defined as a macro, and then the +conditional would succeed. ``#if 0`` can be counted on to fail. + +Do not use ``#if 0`` for comments which are not C code. Use a real +comment, instead. The interior of ``#if 0`` must consist of complete +tokens; in particular, single-quote characters must balance. Comments +often contain unbalanced single-quote characters (known in English as +apostrophes). These confuse ``#if 0``. They don't confuse +:samp:`/*`. \ No newline at end of file diff --git a/gcc/doc/cpp/diagnostics.rst b/gcc/doc/cpp/diagnostics.rst new file mode 100644 index 00000000000..beaad7d8217 --- /dev/null +++ b/gcc/doc/cpp/diagnostics.rst @@ -0,0 +1,51 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: diagnostic, reporting errors, reporting warnings, #error + +.. _diagnostics: + +Diagnostics +----------- + +The directive :samp:`#error` causes the preprocessor to report a fatal +error. The tokens forming the rest of the line following :samp:`#error` +are used as the error message. + +You would use :samp:`#error` inside of a conditional that detects a +combination of parameters which you know the program does not properly +support. For example, if you know that the program will not run +properly on a VAX, you might write + +.. code-block:: c++ + + #ifdef __vax__ + #error "Won't work on VAXen. See comments at get_last_object." + #endif + +If you have several configuration parameters that must be set up by +the installation in a consistent way, you can use conditionals to detect +an inconsistency and report it with :samp:`#error`. For example, + +.. code-block:: c++ + + #if !defined(FOO) && defined(BAR) + #error "BAR requires FOO." + #endif + +.. index:: #warning + +The directive :samp:`#warning` is like :samp:`#error`, but causes the +preprocessor to issue a warning and continue preprocessing. The tokens +following :samp:`#warning` are used as the warning message. + +You might use :samp:`#warning` in obsolete header files, with a message +directing the user to the header file which should be used instead. + +Neither :samp:`#error` nor :samp:`#warning` macro-expands its argument. +Internal whitespace sequences are each replaced with a single space. +The line must consist of complete tokens. It is wisest to make the +argument of these directives be a single string constant; this avoids +problems with apostrophes and the like. \ No newline at end of file diff --git a/gcc/doc/cpp/environment-variables.rst b/gcc/doc/cpp/environment-variables.rst new file mode 100644 index 00000000000..c0ab7992905 --- /dev/null +++ b/gcc/doc/cpp/environment-variables.rst @@ -0,0 +1,23 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: environment variables + +.. _environment-variables: + +Environment Variables +--------------------- + +This section describes the environment variables that affect how CPP +operates. You can use them to specify directories or prefixes to use +when searching for include files, or to control dependency output. + +Note that you can also specify places to search using options such as +:option:`-I`, and control dependency output with options like +:option:`-M` (see :ref:`invocation`). These take precedence over +environment variables, which in turn take precedence over the +configuration of GCC. + +.. include:: ../../../doc/cppenv.rst \ No newline at end of file diff --git a/gcc/doc/cpp/gnu-free-documentation-license.rst b/gcc/doc/cpp/gnu-free-documentation-license.rst new file mode 100644 index 00000000000..1de809b3636 --- /dev/null +++ b/gcc/doc/cpp/gnu-free-documentation-license.rst @@ -0,0 +1,6 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. include:: ../../../doc/gnu_free_documentation_license.rst \ No newline at end of file diff --git a/gcc/doc/cpp/header-files.rst b/gcc/doc/cpp/header-files.rst new file mode 100644 index 00000000000..13b9841c3c6 --- /dev/null +++ b/gcc/doc/cpp/header-files.rst @@ -0,0 +1,56 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: header file + +.. _header-files: + +Header Files +------------ + +A header file is a file containing C declarations and macro definitions +(see :ref:`macros`) to be shared between several source files. You request +the use of a header file in your program by :dfn:`including` it, with the +C preprocessing directive :samp:`#include`. + +Header files serve two purposes. + +.. index:: system header files + +* System header files declare the interfaces to parts of the operating + system. You include them in your program to supply the definitions and + declarations you need to invoke system calls and libraries. + +* Your own header files contain declarations for interfaces between the + source files of your program. Each time you have a group of related + declarations and macro definitions all or most of which are needed in + several different source files, it is a good idea to create a header + file for them. + +Including a header file produces the same results as copying the header +file into each source file that needs it. Such copying would be +time-consuming and error-prone. With a header file, the related +declarations appear in only one place. If they need to be changed, they +can be changed in one place, and programs that include the header file +will automatically use the new version when next recompiled. The header +file eliminates the labor of finding and changing all the copies as well +as the risk that a failure to find one copy will result in +inconsistencies within a program. + +In C, the usual convention is to give header files names that end with +:samp:`.h`. It is most portable to use only letters, digits, dashes, and +underscores in header file names, and at most one dot. + +.. toctree:: + :maxdepth: 2 + + header-files/include-syntax + header-files/include-operation + header-files/search-path + header-files/once-only-headers + header-files/alternatives-to-wrapper-ifndef + header-files/computed-includes + header-files/wrapper-headers + header-files/system-headers \ No newline at end of file diff --git a/gcc/doc/cpp/header-files/alternatives-to-wrapper-ifndef.rst b/gcc/doc/cpp/header-files/alternatives-to-wrapper-ifndef.rst new file mode 100644 index 00000000000..e38cffeaf38 --- /dev/null +++ b/gcc/doc/cpp/header-files/alternatives-to-wrapper-ifndef.rst @@ -0,0 +1,40 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _alternatives-to-wrapper-ifndef: + +Alternatives to Wrapper #ifndef +******************************* + +CPP supports two more ways of indicating that a header file should be +read only once. Neither one is as portable as a wrapper :samp:`#ifndef` +and we recommend you do not use them in new programs, with the caveat +that :samp:`#import` is standard practice in Objective-C. + +.. index:: #import + +CPP supports a variant of :samp:`#include` called :samp:`#import` which +includes a file, but does so at most once. If you use :samp:`#import` +instead of :samp:`#include`, then you don't need the conditionals +inside the header file to prevent multiple inclusion of the contents. +:samp:`#import` is standard in Objective-C, but is considered a +deprecated extension in C and C++. + +:samp:`#import` is not a well designed feature. It requires the users of +a header file to know that it should only be included once. It is much +better for the header file's implementor to write the file so that users +don't need to know this. Using a wrapper :samp:`#ifndef` accomplishes +this goal. + +In the present implementation, a single use of :samp:`#import` will +prevent the file from ever being read again, by either :samp:`#import` or +:samp:`#include`. You should not rely on this; do not use both +:samp:`#import` and :samp:`#include` to refer to the same header file. + +Another way to prevent a header file from being included more than once +is with the :samp:`#pragma once` directive (see :ref:`pragmas`). +:samp:`#pragma once` does not have the problems that :samp:`#import` does, +but it is not recognized by all preprocessors, so you cannot rely on it +in a portable program. \ No newline at end of file diff --git a/gcc/doc/cpp/header-files/computed-includes.rst b/gcc/doc/cpp/header-files/computed-includes.rst new file mode 100644 index 00000000000..49c16228032 --- /dev/null +++ b/gcc/doc/cpp/header-files/computed-includes.rst @@ -0,0 +1,86 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: computed includes, macros in include + +.. _computed-includes: + +Computed Includes +***************** + +Sometimes it is necessary to select one of several different header +files to be included into your program. They might specify +configuration parameters to be used on different sorts of operating +systems, for instance. You could do this with a series of conditionals, + +.. code-block:: c++ + + #if SYSTEM_1 + # include "system_1.h" + #elif SYSTEM_2 + # include "system_2.h" + #elif SYSTEM_3 + ... + #endif + +That rapidly becomes tedious. Instead, the preprocessor offers the +ability to use a macro for the header name. This is called a +:dfn:`computed include`. Instead of writing a header name as the direct +argument of :samp:`#include`, you simply put a macro name there instead: + +.. code-block:: c++ + + #define SYSTEM_H "system_1.h" + ... + #include SYSTEM_H + +``SYSTEM_H`` will be expanded, and the preprocessor will look for +:samp:`system_1.h` as if the :samp:`#include` had been written that way +originally. ``SYSTEM_H`` could be defined by your Makefile with a +:option:`-D` option. + +You must be careful when you define the macro. :samp:`#define` saves +tokens, not text. The preprocessor has no way of knowing that the macro +will be used as the argument of :samp:`#include`, so it generates +ordinary tokens, not a header name. This is unlikely to cause problems +if you use double-quote includes, which are close enough to string +constants. If you use angle brackets, however, you may have trouble. + +The syntax of a computed include is actually a bit more general than the +above. If the first non-whitespace character after :samp:`#include` is +not :samp:`"` or :samp:`<`, then the entire line is macro-expanded +like running text would be. + +If the line expands to a single string constant, the contents of that +string constant are the file to be included. CPP does not re-examine the +string for embedded quotes, but neither does it process backslash +escapes in the string. Therefore + +.. code-block:: c++ + + #define HEADER "a\"b" + #include HEADER + +looks for a file named :samp:`a\\"b`. CPP searches for the file according +to the rules for double-quoted includes. + +If the line expands to a token stream beginning with a :samp:`<` token +and including a :samp:`>` token, then the tokens between the :samp:`<` and +the first :samp:`>` are combined to form the filename to be included. +Any whitespace between tokens is reduced to a single space; then any +space after the initial :samp:`<` is retained, but a trailing space +before the closing :samp:`>` is ignored. CPP searches for the file +according to the rules for angle-bracket includes. + +In either case, if there are any tokens on the line after the file name, +an error occurs and the directive is not processed. It is also an error +if the result of expansion does not match either of the two expected +forms. + +These rules are implementation-defined behavior according to the C +standard. To minimize the risk of different compilers interpreting your +computed includes differently, we recommend you use only a single +object-like macro which expands to a string constant. This will also +minimize confusion for people reading your program. \ No newline at end of file diff --git a/gcc/doc/cpp/header-files/include-operation.rst b/gcc/doc/cpp/header-files/include-operation.rst new file mode 100644 index 00000000000..465905698e7 --- /dev/null +++ b/gcc/doc/cpp/header-files/include-operation.rst @@ -0,0 +1,67 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _include-operation: + +Include Operation +***************** + +The :samp:`#include` directive works by directing the C preprocessor to +scan the specified file as input before continuing with the rest of the +current file. The output from the preprocessor contains the output +already generated, followed by the output resulting from the included +file, followed by the output that comes from the text after the +:samp:`#include` directive. For example, if you have a header file +:samp:`header.h` as follows, + +.. code-block:: c++ + + char *test (void); + +and a main program called :samp:`program.c` that uses the header file, +like this, + +.. code-block:: c++ + + int x; + #include "header.h" + + int + main (void) + { + puts (test ()); + } + +the compiler will see the same token stream as it would if +:samp:`program.c` read + +.. code-block:: c++ + + int x; + char *test (void); + + int + main (void) + { + puts (test ()); + } + +Included files are not limited to declarations and macro definitions; +those are merely the typical uses. Any fragment of a C program can be +included from another file. The include file could even contain the +beginning of a statement that is concluded in the containing file, or +the end of a statement that was started in the including file. However, +an included file must consist of complete tokens. Comments and string +literals which have not been closed by the end of an included file are +invalid. For error recovery, they are considered to end at the end of +the file. + +To avoid confusion, it is best if header files contain only complete +syntactic units---function declarations or definitions, type +declarations, etc. + +The line following the :samp:`#include` directive is always treated as a +separate line by the C preprocessor, even if the included file lacks a +final newline. \ No newline at end of file diff --git a/gcc/doc/cpp/header-files/include-syntax.rst b/gcc/doc/cpp/header-files/include-syntax.rst new file mode 100644 index 00000000000..a378dfc5375 --- /dev/null +++ b/gcc/doc/cpp/header-files/include-syntax.rst @@ -0,0 +1,42 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: #include + +.. _include-syntax: + +Include Syntax +************** + +Both user and system header files are included using the preprocessing +directive :samp:`#include`. It has two variants: + +:samp:`#include <{file}>` + This variant is used for system header files. It searches for a file + named :samp:`{file}` in a standard list of system directories. You can prepend + directories to this list with the :option:`-I` option (see :ref:`invocation`). + +:samp:`#include "{file}"` + This variant is used for header files of your own program. It + searches for a file named :samp:`{file}` first in the directory containing + the current file, then in the quote directories and then the same + directories used for ````. You can prepend directories + to the list of quote directories with the :option:`-iquote` option. + +The argument of :samp:`#include`, whether delimited with quote marks or +angle brackets, behaves like a string constant in that comments are not +recognized, and macro names are not expanded. Thus, ``#include +`` specifies inclusion of a system header file named :samp:`x/*y`. + +However, if backslashes occur within :samp:`{file}`, they are considered +ordinary text characters, not escape characters. None of the character +escape sequences appropriate to string constants in C are processed. +Thus, ``#include "x\n\\y"`` specifies a filename containing three +backslashes. (Some systems interpret :samp:`\\` as a pathname separator. +All of these also interpret :samp:`/` the same way. It is most portable +to use only :samp:`/`.) + +It is an error if there is anything (other than comments) on the line +after the file name. \ No newline at end of file diff --git a/gcc/doc/cpp/header-files/once-only-headers.rst b/gcc/doc/cpp/header-files/once-only-headers.rst new file mode 100644 index 00000000000..2ee77771620 --- /dev/null +++ b/gcc/doc/cpp/header-files/once-only-headers.rst @@ -0,0 +1,52 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: repeated inclusion, including just once, wrapper #ifndef + +.. _once-only-headers: + +Once-Only Headers +***************** + +If a header file happens to be included twice, the compiler will process +its contents twice. This is very likely to cause an error, e.g. when the +compiler sees the same structure definition twice. Even if it does not, +it will certainly waste time. + +The standard way to prevent this is to enclose the entire real contents +of the file in a conditional, like this: + +.. code-block:: c++ + + /* File foo. */ + #ifndef FILE_FOO_SEEN + #define FILE_FOO_SEEN + + the entire file + + #endif /* !FILE_FOO_SEEN */ + +This construct is commonly known as a :dfn:`wrapper #ifndef`. +When the header is included again, the conditional will be false, +because ``FILE_FOO_SEEN`` is defined. The preprocessor will skip +over the entire contents of the file, and the compiler will not see it +twice. + +CPP optimizes even further. It remembers when a header file has a +wrapper :samp:`#ifndef`. If a subsequent :samp:`#include` specifies that +header, and the macro in the :samp:`#ifndef` is still defined, it does +not bother to rescan the file at all. + +You can put comments outside the wrapper. They will not interfere with +this optimization. + +.. index:: controlling macro, guard macro + +The macro ``FILE_FOO_SEEN`` is called the :dfn:`controlling macro` or +:dfn:`guard macro`. In a user header file, the macro name should not +begin with :samp:`_`. In a system header file, it should begin with +:samp:`__` to avoid conflicts with user programs. In any kind of header +file, the macro name should contain the name of the file and some +additional text, to avoid conflicts with other header files. \ No newline at end of file diff --git a/gcc/doc/cpp/header-files/search-path.rst b/gcc/doc/cpp/header-files/search-path.rst new file mode 100644 index 00000000000..9f87878517f --- /dev/null +++ b/gcc/doc/cpp/header-files/search-path.rst @@ -0,0 +1,53 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _search-path: + +Search Path +*********** + +By default, the preprocessor looks for header files included by the quote +form of the directive ``#include "file"`` first relative to +the directory of the current file, and then in a preconfigured list +of standard system directories. +For example, if :samp:`/usr/include/sys/stat.h` contains +``#include "types.h"``, GCC looks for :samp:`types.h` first in +:samp:`/usr/include/sys`, then in its usual search path. + +For the angle-bracket form ``#include ``, the +preprocessor's default behavior is to look only in the standard system +directories. The exact search directory list depends on the target +system, how GCC is configured, and where it is installed. You can +find the default search directory list for your version of CPP by +invoking it with the :option:`-v` option. For example, + +.. code-block:: c++ + + cpp -v /dev/null -o /dev/null + +There are a number of command-line options you can use to add +additional directories to the search path. +The most commonly-used option is :option:`-Idir`, which causes +:samp:`{dir}` to be searched after the current directory (for the quote +form of the directive) and ahead of the standard system directories. +You can specify multiple :option:`-I` options on the command line, +in which case the directories are searched in left-to-right order. + +If you need separate control over the search paths for the quote and +angle-bracket forms of the :samp:`#include` directive, you can use the +:option:`-iquote` and/or :option:`-isystem` options instead of :option:`-I`. +See :ref:`invocation`, for a detailed description of these options, as +well as others that are less generally useful. + +If you specify other options on the command line, such as :option:`-I`, +that affect where the preprocessor searches for header files, the +directory list printed by the :option:`-v` option reflects the actual +search path used by the preprocessor. + +Note that you can also prevent the preprocessor from searching any of +the default system header directories with the :option:`-nostdinc` +option. This is useful when you are compiling an operating system +kernel or some other program that does not use the standard C library +facilities, or the standard C library itself. \ No newline at end of file diff --git a/gcc/doc/cpp/header-files/system-headers.rst b/gcc/doc/cpp/header-files/system-headers.rst new file mode 100644 index 00000000000..ef6474f9dea --- /dev/null +++ b/gcc/doc/cpp/header-files/system-headers.rst @@ -0,0 +1,41 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: system header files + +.. _system-headers: + +System Headers +************** + +The header files declaring interfaces to the operating system and +runtime libraries often cannot be written in strictly conforming C. +Therefore, GCC gives code found in :dfn:`system headers` special +treatment. All warnings, other than those generated by :samp:`#warning` +(see :ref:`diagnostics`), are suppressed while GCC is processing a system +header. Macros defined in a system header are immune to a few warnings +wherever they are expanded. This immunity is granted on an ad-hoc +basis, when we find that a warning generates lots of false positives +because of code in macros defined in system headers. + +Normally, only the headers found in specific directories are considered +system headers. These directories are determined when GCC is compiled. +There are, however, two ways to make normal headers into system headers: + +* Header files found in directories added to the search path with the + :option:`-isystem` and :option:`-idirafter` command-line options are + treated as system headers for the purposes of diagnostics. + +* + .. index:: #pragma GCC system_header + + There is also a directive, ``#pragma GCC system_header``, which + tells GCC to consider the rest of the current include file a system + header, no matter where it was found. Code that comes before the + :samp:`#pragma` in the file is not affected. ``#pragma GCC + system_header`` has no effect in the primary source file. + +On some targets, such as RS/6000 AIX, GCC implicitly surrounds all +system headers with an :samp:`extern "C"` block when compiling as C++. \ No newline at end of file diff --git a/gcc/doc/cpp/header-files/wrapper-headers.rst b/gcc/doc/cpp/header-files/wrapper-headers.rst new file mode 100644 index 00000000000..848170e138e --- /dev/null +++ b/gcc/doc/cpp/header-files/wrapper-headers.rst @@ -0,0 +1,58 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: wrapper headers, overriding a header file, #include_next + +.. _wrapper-headers: + +Wrapper Headers +*************** + +Sometimes it is necessary to adjust the contents of a system-provided +header file without editing it directly. GCC's :command:`fixincludes` +operation does this, for example. One way to do that would be to create +a new header file with the same name and insert it in the search path +before the original header. That works fine as long as you're willing +to replace the old header entirely. But what if you want to refer to +the old header from the new one? + +You cannot simply include the old header with :samp:`#include`. That +will start from the beginning, and find your new header again. If your +header is not protected from multiple inclusion (see :ref:`once-only-headers`), it will recurse infinitely and cause a fatal error. + +You could include the old header with an absolute pathname: + +.. code-block:: c++ + + #include "/usr/include/old-header.h" + +This works, but is not clean; should the system headers ever move, you +would have to edit the new headers to match. + +There is no way to solve this problem within the C standard, but you can +use the GNU extension :samp:`#include_next`. It means, 'Include the +*next* file with this name'. This directive works like +:samp:`#include` except in searching for the specified file: it starts +searching the list of header file directories *after* the directory +in which the current file was found. + +Suppose you specify :option:`-I /usr/local/include`, and the list of +directories to search also includes :samp:`/usr/include`; and suppose +both directories contain :samp:`signal.h`. Ordinary ``#include +`` finds the file under :samp:`/usr/local/include`. If that +file contains ``#include_next ``, it starts searching +after that directory, and finds the file in :samp:`/usr/include`. + +:samp:`#include_next` does not distinguish between ```` +and ``"file"`` inclusion, nor does it check that the file you +specify has the same name as the current file. It simply looks for the +file named, starting with the directory in the search path after the one +where the current file was found. + +The use of :samp:`#include_next` can lead to great confusion. We +recommend it be used only when there is no other alternative. In +particular, it should not be used in the headers belonging to a specific +program; it should be used only to make global corrections along the +lines of :command:`fixincludes`. \ No newline at end of file diff --git a/gcc/doc/cpp/implementation-defined-behavior.rst b/gcc/doc/cpp/implementation-defined-behavior.rst new file mode 100644 index 00000000000..8946520eefe --- /dev/null +++ b/gcc/doc/cpp/implementation-defined-behavior.rst @@ -0,0 +1,97 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _implementation-defined-behavior: + +.. _identifier-characters: + +Implementation-defined behavior +******************************* + +This is how CPP behaves in all the cases which the C standard +describes as :dfn:`implementation-defined`. This term means that the +implementation is free to do what it likes, but must document its choice +and stick to it. + +.. todo:: Check the C++ standard for more implementation-defined stuff. + +* The mapping of physical source file multi-byte characters to the + execution character set. + + The input character set can be specified using the + :option:`-finput-charset` option, while the execution character set may + be controlled using the :option:`-fexec-charset` and + :option:`-fwide-exec-charset` options. + +* Identifier characters. + + The C and C++ standards allow identifiers to be composed of :samp:`_` + and the alphanumeric characters. C++ also allows universal character + names. C99 and later C standards permit both universal character + names and implementation-defined characters. In both C and C++ modes, + GCC accepts in identifiers exactly those extended characters that + correspond to universal character names permitted by the chosen + standard. + + GCC allows the :samp:`$` character in identifiers as an extension for + most targets. This is true regardless of the std= switch, + since this extension cannot conflict with standards-conforming + programs. When preprocessing assembler, however, dollars are not + identifier characters by default. + + Currently the targets that by default do not permit :samp:`$` are AVR, + IP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX + operating system. + + You can override the default with :option:`-fdollars-in-identifiers` or + :option:`-fno-dollars-in-identifiers`. See :option:`-fdollars-in-identifiers`. + +* Non-empty sequences of whitespace characters. + + In textual output, each whitespace sequence is collapsed to a single + space. For aesthetic reasons, the first token on each non-directive + line of output is preceded with sufficient spaces that it appears in the + same column as it did in the original source file. + +* The numeric value of character constants in preprocessor expressions. + + The preprocessor and compiler interpret character constants in the + same way; i.e. escape sequences such as :samp:`\\a` are given the + values they would have on the target machine. + + The compiler evaluates a multi-character character constant a character + at a time, shifting the previous value left by the number of bits per + target character, and then or-ing in the bit-pattern of the new + character truncated to the width of a target character. The final + bit-pattern is given type ``int``, and is therefore signed, + regardless of whether single characters are signed or not. + If there are more + characters in the constant than would fit in the target ``int`` the + compiler issues a warning, and the excess leading characters are + ignored. + + For example, ``'ab'`` for a target with an 8-bit ``char`` would be + interpreted as :samp:`(int) ((unsigned char) 'a' * 256 + (unsigned char) + 'b')`, and ``'\234a'`` as :samp:`(int) ((unsigned char) '\\234' * + 256 + (unsigned char) 'a')`. + +* Source file inclusion. + + For a discussion on how the preprocessor locates header files, + :ref:`include-operation`. + +* Interpretation of the filename resulting from a macro-expanded + :samp:`#include` directive. + + See :ref:`computed-includes`. + +* Treatment of a :samp:`#pragma` directive that after macro-expansion + results in a standard pragma. + + No macro expansion occurs on any :samp:`#pragma` directive line, so the + question does not arise. + + Note that GCC does not yet implement any of the standard + pragmas. \ No newline at end of file diff --git a/gcc/doc/cpp/implementation-details.rst b/gcc/doc/cpp/implementation-details.rst new file mode 100644 index 00000000000..326277b1fc9 --- /dev/null +++ b/gcc/doc/cpp/implementation-details.rst @@ -0,0 +1,23 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _implementation-details: + +Implementation Details +---------------------- + +Here we document details of how the preprocessor's implementation +affects its user-visible behavior. You should try to avoid undue +reliance on behavior described here, as it is possible that it will +change subtly in future implementations. + +Also documented here are obsolete features still supported by CPP. + +.. toctree:: + :maxdepth: 2 + + implementation-defined-behavior + implementation-limits + obsolete-features \ No newline at end of file diff --git a/gcc/doc/cpp/implementation-limits.rst b/gcc/doc/cpp/implementation-limits.rst new file mode 100644 index 00000000000..18cfc6ab0a6 --- /dev/null +++ b/gcc/doc/cpp/implementation-limits.rst @@ -0,0 +1,68 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: implementation limits + +.. _implementation-limits: + +Implementation limits +********************* + +CPP has a small number of internal limits. This section lists the +limits which the C standard requires to be no lower than some minimum, +and all the others known. It is intended that there should be as few limits +as possible. If you encounter an undocumented or inconvenient limit, +please report that as a bug. See :ref:`gcc:bugs`. + +Where we say something is limited :dfn:`only by available memory`, that +means that internal data structures impose no intrinsic limit, and space +is allocated with ``malloc`` or equivalent. The actual limit will +therefore depend on many things, such as the size of other things +allocated by the compiler at the same time, the amount of memory +consumed by other processes on the same computer, etc. + +* Nesting levels of :samp:`#include` files. + + We impose an arbitrary limit of 200 levels, to avoid runaway recursion. + The standard requires at least 15 levels. + +* Nesting levels of conditional inclusion. + + The C standard mandates this be at least 63. CPP is limited only by + available memory. + +* Levels of parenthesized expressions within a full expression. + + The C standard requires this to be at least 63. In preprocessor + conditional expressions, it is limited only by available memory. + +* Significant initial characters in an identifier or macro name. + + The preprocessor treats all characters as significant. The C standard + requires only that the first 63 be significant. + +* Number of macros simultaneously defined in a single translation unit. + + The standard requires at least 4095 be possible. CPP is limited only + by available memory. + +* Number of parameters in a macro definition and arguments in a macro call. + + We allow ``USHRT_MAX``, which is no smaller than 65,535. The minimum + required by the standard is 127. + +* Number of characters on a logical source line. + + The C standard requires a minimum of 4096 be permitted. CPP places + no limits on this, but you may get incorrect column numbers reported in + diagnostics for lines longer than 65,535 characters. + +* Maximum size of a source file. + + The standard does not specify any lower limit on the maximum size of a + source file. GNU cpp maps files into memory, so it is limited by the + available address space. This is generally at least two gigabytes. + Depending on the operating system, the size of physical memory may or + may not be a limitation. \ No newline at end of file diff --git a/gcc/doc/cpp/index.rst b/gcc/doc/cpp/index.rst new file mode 100644 index 00000000000..e19dfba42a6 --- /dev/null +++ b/gcc/doc/cpp/index.rst @@ -0,0 +1,35 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +The C Preprocessor +================== + +The C preprocessor implements the macro language used to transform C, +C++, and Objective-C programs before they are compiled. It can also be +useful on its own. + +.. only:: html + + Contents: + +.. toctree:: + + copyright + overview + header-files + macros + conditionals + diagnostics + line-control + pragmas + other-directives + preprocessor-output + traditional-mode + implementation-details + invocation + environment-variables + gnu-free-documentation-license + + indices-and-tables \ No newline at end of file diff --git a/gcc/doc/cpp/indices-and-tables.rst b/gcc/doc/cpp/indices-and-tables.rst new file mode 100644 index 00000000000..6c215a391d9 --- /dev/null +++ b/gcc/doc/cpp/indices-and-tables.rst @@ -0,0 +1 @@ +.. include:: ../../../doc/indices-and-tables.rst \ No newline at end of file diff --git a/gcc/doc/cpp/initial-processing.rst b/gcc/doc/cpp/initial-processing.rst new file mode 100644 index 00000000000..9ca96f21428 --- /dev/null +++ b/gcc/doc/cpp/initial-processing.rst @@ -0,0 +1,164 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _initial-processing: + +Initial processing +****************** + +The preprocessor performs a series of textual transformations on its +input. These happen before all other processing. Conceptually, they +happen in a rigid order, and the entire file is run through each +transformation before the next one begins. CPP actually does them +all at once, for performance reasons. These transformations correspond +roughly to the first three 'phases of translation' described in the C +standard. + +.. index:: line endings + +* The input file is read into memory and broken into lines. + + Different systems use different conventions to indicate the end of a + line. GCC accepts the ASCII control sequences LF, CR + LF and CR as end-of-line markers. These are the canonical + sequences used by Unix, DOS and VMS, and the classic Mac OS (before + OSX) respectively. You may therefore safely copy source code written + on any of those systems to a different one and use it without + conversion. (GCC may lose track of the current line number if a file + doesn't consistently use one convention, as sometimes happens when it + is edited on computers with different conventions that share a network + file system.) + + If the last line of any input file lacks an end-of-line marker, the end + of the file is considered to implicitly supply one. The C standard says + that this condition provokes undefined behavior, so GCC will emit a + warning message. + +.. index:: trigraphs + +.. _trigraphs: + +* If trigraphs are enabled, they are replaced by their + corresponding single characters. By default GCC ignores trigraphs, + but if you request a strictly conforming mode with the :option:`-std` + option, or you specify the :option:`-trigraphs` option, then it + converts them. + + These are nine three-character sequences, all starting with :samp:`??`, + that are defined by ISO C to stand for single characters. They permit + obsolete systems that lack some of C's punctuation to use C. For + example, :samp:`??/` stands for :samp:`\\`, so ``'??/n'`` is a character + constant for a newline. + + Trigraphs are not popular and many compilers implement them + incorrectly. Portable code should not rely on trigraphs being either + converted or ignored. With :option:`-Wtrigraphs` GCC will warn you + when a trigraph may change the meaning of your program if it were + converted. See :ref:`wtrigraphs`. + + In a string constant, you can prevent a sequence of question marks + from being confused with a trigraph by inserting a backslash between + the question marks, or by separating the string literal at the + trigraph and making use of string literal concatenation. ``"(??\?)"`` + is the string :samp:`(???)`, not :samp:`(?]`. Traditional C compilers + do not recognize these idioms. + + The nine trigraphs and their replacements are + + .. code-block:: + + Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- + Replacement: [ ] { } # \ ^ | ~ + +.. index:: continued lines, backslash-newline + +* Continued lines are merged into one long line. + + A continued line is a line which ends with a backslash, :samp:`\\`. The + backslash is removed and the following line is joined with the current + one. No space is inserted, so you may split a line anywhere, even in + the middle of a word. (It is generally more readable to split lines + only at white space.) + + The trailing backslash on a continued line is commonly referred to as a + :dfn:`backslash-newline`. + + If there is white space between a backslash and the end of a line, that + is still a continued line. However, as this is usually the result of an + editing mistake, and many compilers will not accept it as a continued + line, GCC will warn you about it. + +.. index:: comments, line comments, block comments + +* All comments are replaced with single spaces. + + There are two kinds of comments. :dfn:`Block comments` begin with + :samp:`/*` and continue until the next :samp:`*/`. Block comments do not + nest: + + .. code-block:: c++ + + /* this is /* one comment */ text outside comment + + :dfn:`Line comments` begin with :samp:`//` and continue to the end of the + current line. Line comments do not nest either, but it does not matter, + because they would end in the same place anyway. + + .. code-block:: c++ + + // this is // one comment + text outside comment + +It is safe to put line comments inside block comments, or vice versa. + +.. code-block:: c++ + + /* block comment + // contains line comment + yet more comment + */ outside comment + + // line comment /* contains block comment */ + +But beware of commenting out one end of a block comment with a line +comment. + +.. code-block:: + + // l.c. /* block comment begins + oops! this isn't a comment anymore */ + +Comments are not recognized within string literals. +``"/* blah */"`` is the string constant :samp:`/\* blah \*/`, not +an empty string. + +Line comments are not in the 1989 edition of the C standard, but they +are recognized by GCC as an extension. In C++ and in the 1999 edition +of the C standard, they are an official part of the language. + +Since these transformations happen before all other processing, you can +split a line mechanically with backslash-newline anywhere. You can +comment out the end of a line. You can continue a line comment onto the +next line with backslash-newline. You can even split :samp:`/*`, +:samp:`*/`, and :samp:`//` onto multiple lines with backslash-newline. +For example: + +.. code-block:: + + /\ + * + */ # /* + */ defi\ + ne FO\ + O 10\ + 20 + +is equivalent to ``#define FOO 1020``. All these tricks are +extremely confusing and should not be used in code intended to be +readable. + +There is no way to prevent a backslash at the end of a line from being +interpreted as a backslash-newline. This cannot affect any correct +program, however. \ No newline at end of file diff --git a/gcc/doc/cpp/invocation.rst b/gcc/doc/cpp/invocation.rst new file mode 100644 index 00000000000..7b13980af5a --- /dev/null +++ b/gcc/doc/cpp/invocation.rst @@ -0,0 +1,81 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: invocation, command line + +.. _invocation: + +Invocation +---------- + +Most often when you use the C preprocessor you do not have to invoke it +explicitly: the C compiler does so automatically. However, the +preprocessor is sometimes useful on its own. You can invoke the +preprocessor either with the :command:`cpp` command, or via :command:`gcc -E`. +In GCC, the preprocessor is actually integrated with the compiler +rather than a separate program, and both of these commands invoke +GCC and tell it to stop after the preprocessing phase. + +The :command:`cpp` options listed here are also accepted by +:command:`gcc` and have the same meaning. Likewise the :command:`cpp` +command accepts all the usual :command:`gcc` driver options, although those +pertaining to compilation phases after preprocessing are ignored. + +Only options specific to preprocessing behavior are documented here. +Refer to the GCC manual for full documentation of other driver options. + +.. only:: man + + Synopsis + ^^^^^^^^ + + cpp [ :option:`-D`:samp:`{macro}` [= :samp:`{defn}` ]...] [ :option:`-U`:samp:`{macro}` ] + [ :option:`-I`:samp:`{dir}`...] [ :option:`-iquote`:samp:`{dir}`...] + [ :option:`-M` | :option:`-MM` ] [ :option:`-MG` ] [ :option:`-MF` :samp:`{filename}` ] + [ :option:`-MP` ] [ :option:`-MQ` :samp:`{target}`...] + [ :option:`-MT` :samp:`{target}`...] + :samp:`{infile}` [[ :option:`-o` ] :samp:`{outfile}` ] + + Only the most useful options are given above; see below for a more + complete list of preprocessor-specific options. + In addition, :command:`cpp` accepts most :command:`gcc` driver options, which + are not listed here. Refer to the GCC documentation for details. + +Options +^^^^^^^ + +The :command:`cpp` command expects two file names as arguments, :samp:`{infile}` and +:samp:`{outfile}`. The preprocessor reads :samp:`{infile}` together with any +other files it specifies with :samp:`#include`. All the output generated +by the combined input files is written in :samp:`{outfile}`. + +Either :samp:`{infile}` or :samp:`{outfile}` may be :option:`-`, which as +:samp:`{infile}` means to read from standard input and as :samp:`{outfile}` +means to write to standard output. If either file is omitted, it +means the same as if :option:`-` had been specified for that file. +You can also use the :option:`-o outfile` option to specify the +output file. + +Unless otherwise noted, or the option ends in :samp:`=`, all options +which take an argument may have that argument appear either immediately +after the option, or with a space between option and argument: +:option:`-Ifoo` and :option:`-I foo` have the same effect. + +.. index:: grouping options, options, grouping + +Many options have multi-letter names; therefore multiple single-letter +options may *not* be grouped: :option:`-dM` is very different from +:samp:`-d -M`. + +.. index:: options + +.. include:: ../../../doc/cppopts.rst + + +.. include:: ../../../doc/cppdiropts.rst + +.. only:: man + + .. include:: copyright.rst \ No newline at end of file diff --git a/gcc/doc/cpp/line-control.rst b/gcc/doc/cpp/line-control.rst new file mode 100644 index 00000000000..933d8a9cf1c --- /dev/null +++ b/gcc/doc/cpp/line-control.rst @@ -0,0 +1,55 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: line control + +.. _line-control: + +Line Control +------------ + +The C preprocessor informs the C compiler of the location in your source +code where each token came from. Presently, this is just the file name +and line number. All the tokens resulting from macro expansion are +reported as having appeared on the line of the source file where the +outermost macro was used. We intend to be more accurate in the future. + +If you write a program which generates source code, such as the +:command:`bison` parser generator, you may want to adjust the preprocessor's +notion of the current file name and line number by hand. Parts of the +output from :command:`bison` are generated from scratch, other parts come +from a standard parser file. The rest are copied verbatim from +:command:`bison`'s input. You would like compiler error messages and +symbolic debuggers to be able to refer to ``bison`` 's input file. + +.. index:: #line + +:command:`bison` or any such program can arrange this by writing +:samp:`#line` directives into the output file. :samp:`#line` is a +directive that specifies the original line number and source file name +for subsequent input in the current preprocessor input file. +:samp:`#line` has three variants: + +:samp:`#line {linenum}` + :samp:`{linenum}` is a non-negative decimal integer constant. It specifies + the line number which should be reported for the following line of + input. Subsequent lines are counted from :samp:`{linenum}`. + +:samp:`#line {linenum}{filename}` + :samp:`{linenum}` is the same as for the first form, and has the same + effect. In addition, :samp:`{filename}` is a string constant. The + following line and all subsequent lines are reported to come from the + file it specifies, until something else happens to change that. + :samp:`{filename}` is interpreted according to the normal rules for a string + constant: backslash escapes are interpreted. This is different from + :samp:`#include`. + +:samp:`#line {anything else}` + :samp:`{anything else}` is checked for macro calls, which are expanded. + The result should match one of the above two forms. + +:samp:`#line` directives alter the results of the ``__FILE__`` and +``__LINE__`` predefined macros from that point on. See :ref:`standard-predefined-macros`. They do not have any effect on :samp:`#include`'s +idea of the directory containing the current file. \ No newline at end of file diff --git a/gcc/doc/cpp/macros.rst b/gcc/doc/cpp/macros.rst new file mode 100644 index 00000000000..7355e0719ef --- /dev/null +++ b/gcc/doc/cpp/macros.rst @@ -0,0 +1,37 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _macros: + +Macros +------ + +A :dfn:`macro` is a fragment of code which has been given a name. +Whenever the name is used, it is replaced by the contents of the macro. +There are two kinds of macros. They differ mostly in what they look +like when they are used. :dfn:`Object-like` macros resemble data objects +when used, :dfn:`function-like` macros resemble function calls. + +You may define any valid identifier as a macro, even if it is a C +keyword. The preprocessor does not know anything about keywords. This +can be useful if you wish to hide a keyword such as ``const`` from an +older compiler that does not understand it. However, the preprocessor +operator ``defined`` (see :ref:`defined`) can never be defined as a +macro, and C++'s named operators (see :ref:`c++-named-operators`) cannot be +macros when you are compiling C++. + +.. toctree:: + :maxdepth: 2 + + macros/object-like-macros + macros/function-like-macros + macros/macro-arguments + macros/stringizing + macros/concatenation + macros/variadic-macros + macros/predefined-macros + macros/undefining-and-redefining-macros + macros/directives-within-macro-arguments + macros/macro-pitfalls \ No newline at end of file diff --git a/gcc/doc/cpp/macros/concatenation.rst b/gcc/doc/cpp/macros/concatenation.rst new file mode 100644 index 00000000000..2f5066ab65e --- /dev/null +++ b/gcc/doc/cpp/macros/concatenation.rst @@ -0,0 +1,85 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: concatenation, token pasting, token concatenation, ## operator + +.. _concatenation: + +Concatenation +************* + +It is often useful to merge two tokens into one while expanding macros. +This is called :dfn:`token pasting` or :dfn:`token concatenation`. The +:samp:`##` preprocessing operator performs token pasting. When a macro +is expanded, the two tokens on either side of each :samp:`##` operator +are combined into a single token, which then replaces the :samp:`##` and +the two original tokens in the macro expansion. Usually both will be +identifiers, or one will be an identifier and the other a preprocessing +number. When pasted, they make a longer identifier. This isn't the +only valid case. It is also possible to concatenate two numbers (or a +number and a name, such as ``1.5`` and ``e3``) into a number. +Also, multi-character operators such as ``+=`` can be formed by +token pasting. + +However, two tokens that don't together form a valid token cannot be +pasted together. For example, you cannot concatenate ``x`` with +``+`` in either order. If you try, the preprocessor issues a warning +and emits the two tokens. Whether it puts white space between the +tokens is undefined. It is common to find unnecessary uses of :samp:`##` +in complex macros. If you get this warning, it is likely that you can +simply remove the :samp:`##`. + +Both the tokens combined by :samp:`##` could come from the macro body, +but you could just as well write them as one token in the first place. +Token pasting is most useful when one or both of the tokens comes from a +macro argument. If either of the tokens next to an :samp:`##` is a +parameter name, it is replaced by its actual argument before :samp:`##` +executes. As with stringizing, the actual argument is not +macro-expanded first. If the argument is empty, that :samp:`##` has no +effect. + +Keep in mind that the C preprocessor converts comments to whitespace +before macros are even considered. Therefore, you cannot create a +comment by concatenating :samp:`/` and :samp:`*`. You can put as much +whitespace between :samp:`##` and its operands as you like, including +comments, and you can put comments in arguments that will be +concatenated. However, it is an error if :samp:`##` appears at either +end of a macro body. + +Consider a C program that interprets named commands. There probably +needs to be a table of commands, perhaps an array of structures declared +as follows: + +.. code-block:: c++ + + struct command + { + char *name; + void (*function) (void); + }; + + struct command commands[] = + { + { "quit", quit_command }, + { "help", help_command }, + ... + }; + +It would be cleaner not to have to give each command name twice, once in +the string constant and once in the function name. A macro which takes the +name of a command as an argument can make this unnecessary. The string +constant can be created with stringizing, and the function name by +concatenating the argument with :samp:`_command`. Here is how it is done: + +.. code-block:: c++ + + #define COMMAND(NAME) { #NAME, NAME ## _command } + + struct command commands[] = + { + COMMAND (quit), + COMMAND (help), + ... + }; \ No newline at end of file diff --git a/gcc/doc/cpp/macros/directives-within-macro-arguments.rst b/gcc/doc/cpp/macros/directives-within-macro-arguments.rst new file mode 100644 index 00000000000..2e7e82563e9 --- /dev/null +++ b/gcc/doc/cpp/macros/directives-within-macro-arguments.rst @@ -0,0 +1,39 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: macro arguments and directives + +.. _directives-within-macro-arguments: + +Directives Within Macro Arguments +********************************* + +Occasionally it is convenient to use preprocessor directives within +the arguments of a macro. The C and C++ standards declare that +behavior in these cases is undefined. GNU CPP +processes arbitrary directives within macro arguments in +exactly the same way as it would have processed the directive were the +function-like macro invocation not present. + +If, within a macro invocation, that macro is redefined, then the new +definition takes effect in time for argument pre-expansion, but the +original definition is still used for argument replacement. Here is a +pathological example: + +.. code-block:: c++ + + #define f(x) x x + f (1 + #undef f + #define f 2 + f) + +which expands to + +.. code-block:: c++ + + 1 2 1 2 + +with the semantics described above. \ No newline at end of file diff --git a/gcc/doc/cpp/macros/function-like-macros.rst b/gcc/doc/cpp/macros/function-like-macros.rst new file mode 100644 index 00000000000..16ba2cf1a1a --- /dev/null +++ b/gcc/doc/cpp/macros/function-like-macros.rst @@ -0,0 +1,55 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: function-like macros + +.. _function-like-macros: + +Function-like Macros +******************** + +You can also define macros whose use looks like a function call. These +are called :dfn:`function-like macros`. To define a function-like macro, +you use the same :samp:`#define` directive, but you put a pair of +parentheses immediately after the macro name. For example, + +.. code-block:: + + #define lang_init() c_init() + lang_init() + → c_init() + +A function-like macro is only expanded if its name appears with a pair +of parentheses after it. If you write just the name, it is left alone. +This can be useful when you have a function and a macro of the same +name, and you wish to use the function sometimes. + +.. code-block:: + + extern void foo(void); + #define foo() /* optimized inline version */ + ... + foo(); + funcptr = foo; + +Here the call to ``foo()`` will use the macro, but the function +pointer will get the address of the real function. If the macro were to +be expanded, it would cause a syntax error. + +If you put spaces between the macro name and the parentheses in the +macro definition, that does not define a function-like macro, it defines +an object-like macro whose expansion happens to begin with a pair of +parentheses. + +.. code-block:: + + #define lang_init () c_init() + lang_init() + → () c_init()() + +The first two pairs of parentheses in this expansion come from the +macro. The third is the pair that was originally after the macro +invocation. Since ``lang_init`` is an object-like macro, it does not +consume those parentheses. \ No newline at end of file diff --git a/gcc/doc/cpp/macros/macro-arguments.rst b/gcc/doc/cpp/macros/macro-arguments.rst new file mode 100644 index 00000000000..06911523e7f --- /dev/null +++ b/gcc/doc/cpp/macros/macro-arguments.rst @@ -0,0 +1,112 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: arguments, macros with arguments, arguments in macro definitions + +.. _macro-arguments: + +Macro Arguments +*************** + +Function-like macros can take :dfn:`arguments`, just like true functions. +To define a macro that uses arguments, you insert :dfn:`parameters` +between the pair of parentheses in the macro definition that make the +macro function-like. The parameters must be valid C identifiers, +separated by commas and optionally whitespace. + +To invoke a macro that takes arguments, you write the name of the macro +followed by a list of :dfn:`actual arguments` in parentheses, separated +by commas. The invocation of the macro need not be restricted to a +single logical line---it can cross as many lines in the source file as +you wish. The number of arguments you give must match the number of +parameters in the macro definition. When the macro is expanded, each +use of a parameter in its body is replaced by the tokens of the +corresponding argument. (You need not use all of the parameters in the +macro body.) + +As an example, here is a macro that computes the minimum of two numeric +values, as it is defined in many C programs, and some uses. + +.. code-block:: + + #define min(X, Y) ((X) < (Y) ? (X) : (Y)) + x = min(a, b); → x = ((a) < (b) ? (a) : (b)); + y = min(1, 2); → y = ((1) < (2) ? (1) : (2)); + z = min(a + 28, *p); → z = ((a + 28) < (*p) ? (a + 28) : (*p)); + +(In this small example you can already see several of the dangers of +macro arguments. See :ref:`macro-pitfalls`, for detailed explanations.) + +Leading and trailing whitespace in each argument is dropped, and all +whitespace between the tokens of an argument is reduced to a single +space. Parentheses within each argument must balance; a comma within +such parentheses does not end the argument. However, there is no +requirement for square brackets or braces to balance, and they do not +prevent a comma from separating arguments. Thus, + +.. code-block:: c++ + + macro (array[x = y, x + 1]) + +passes two arguments to ``macro`` : ``array[x = y`` and ``x + +1]``. If you want to supply ``array[x = y, x + 1]`` as an argument, +you can write it as ``array[(x = y, x + 1)]``, which is equivalent C +code. + +All arguments to a macro are completely macro-expanded before they are +substituted into the macro body. After substitution, the complete text +is scanned again for macros to expand, including the arguments. This rule +may seem strange, but it is carefully designed so you need not worry +about whether any function call is actually a macro invocation. You can +run into trouble if you try to be too clever, though. See :ref:`argument-prescan`, for detailed discussion. + +For example, ``min (min (a, b), c)`` is first expanded to + +.. code-block:: c++ + + min (((a) < (b) ? (a) : (b)), (c)) + +and then to + +.. code-block:: c++ + + ((((a) < (b) ? (a) : (b))) < (c) + ? (((a) < (b) ? (a) : (b))) + : (c)) + +(Line breaks shown here for clarity would not actually be generated.) + +.. index:: empty macro arguments + +You can leave macro arguments empty; this is not an error to the +preprocessor (but many macros will then expand to invalid code). +You cannot leave out arguments entirely; if a macro takes two arguments, +there must be exactly one comma at the top level of its argument list. +Here are some silly examples using ``min`` : + +.. code-block:: + + min(, b) → (( ) < (b) ? ( ) : (b)) + min(a, ) → ((a ) < ( ) ? (a ) : ( )) + min(,) → (( ) < ( ) ? ( ) : ( )) + min((,),) → (((,)) < ( ) ? ((,)) : ( )) + + min() error macro "min" requires 2 arguments, but only 1 given + min(,,) error macro "min" passed 3 arguments, but takes just 2 + +Whitespace is not a preprocessing token, so if a macro ``foo`` takes +one argument, ``foo ()`` and ``foo ( )`` both supply it an +empty argument. Previous GNU preprocessor implementations and +documentation were incorrect on this point, insisting that a +function-like macro that takes a single argument be passed a space if an +empty argument was required. + +Macro parameters appearing inside string literals are not replaced by +their corresponding actual arguments. + +.. code-block:: + + #define foo(x) x, "x" + foo(bar) → bar, "x" \ No newline at end of file diff --git a/gcc/doc/cpp/macros/macro-pitfalls.rst b/gcc/doc/cpp/macros/macro-pitfalls.rst new file mode 100644 index 00000000000..0be22954a76 --- /dev/null +++ b/gcc/doc/cpp/macros/macro-pitfalls.rst @@ -0,0 +1,449 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: problems with macros, pitfalls of macros + +.. _macro-pitfalls: + +Macro Pitfalls +************** + +In this section we describe some special rules that apply to macros and +macro expansion, and point out certain cases in which the rules have +counter-intuitive consequences that you must watch out for. + +.. toctree:: + :maxdepth: 2 + + +.. _misnesting: + +Misnesting +^^^^^^^^^^ + +When a macro is called with arguments, the arguments are substituted +into the macro body and the result is checked, together with the rest of +the input file, for more macro calls. It is possible to piece together +a macro call coming partially from the macro body and partially from the +arguments. For example, + +.. code-block:: + + #define twice(x) (2*(x)) + #define call_with_1(x) x(1) + call_with_1 (twice) + → twice(1) + → (2*(1)) + +Macro definitions do not have to have balanced parentheses. By writing +an unbalanced open parenthesis in a macro body, it is possible to create +a macro call that begins inside the macro body but ends outside of it. +For example, + +.. code-block:: + + #define strange(file) fprintf (file, "%s %d", + ... + strange(stderr) p, 35) + → fprintf (stderr, "%s %d", p, 35) + +The ability to piece together a macro call can be useful, but the use of +unbalanced open parentheses in a macro body is just confusing, and +should be avoided. + +.. index:: parentheses in macro bodies + +.. _operator-precedence-problems: + +Operator Precedence Problems +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You may have noticed that in most of the macro definition examples shown +above, each occurrence of a macro argument name had parentheses around +it. In addition, another pair of parentheses usually surround the +entire macro definition. Here is why it is best to write macros that +way. + +Suppose you define a macro as follows, + +.. code-block:: c++ + + #define ceil_div(x, y) (x + y - 1) / y + +whose purpose is to divide, rounding up. (One use for this operation is +to compute how many ``int`` objects are needed to hold a certain +number of ``char`` objects.) Then suppose it is used as follows: + +.. code-block:: + + a = ceil_div (b & c, sizeof (int)); + → a = (b & c + sizeof (int) - 1) / sizeof (int); + +This does not do what is intended. The operator-precedence rules of +C make it equivalent to this: + +.. code-block:: c++ + + a = (b & (c + sizeof (int) - 1)) / sizeof (int); + +What we want is this: + +.. code-block:: c++ + + a = ((b & c) + sizeof (int) - 1)) / sizeof (int); + +Defining the macro as + +.. code-block:: c++ + + #define ceil_div(x, y) ((x) + (y) - 1) / (y) + +provides the desired result. + +Unintended grouping can result in another way. Consider ``sizeof +ceil_div(1, 2)``. That has the appearance of a C expression that would +compute the size of the type of ``ceil_div (1, 2)``, but in fact it +means something very different. Here is what it expands to: + +.. code-block:: c++ + + sizeof ((1) + (2) - 1) / (2) + +This would take the size of an integer and divide it by two. The +precedence rules have put the division outside the ``sizeof`` when it +was intended to be inside. + +Parentheses around the entire macro definition prevent such problems. +Here, then, is the recommended way to define ``ceil_div`` : + +.. code-block:: c++ + + #define ceil_div(x, y) (((x) + (y) - 1) / (y)) + +.. index:: semicolons (after macro calls) + +.. _swallowing-the-semicolon: + +Swallowing the Semicolon +^^^^^^^^^^^^^^^^^^^^^^^^ + +Often it is desirable to define a macro that expands into a compound +statement. Consider, for example, the following macro, that advances a +pointer (the argument ``p`` says where to find it) across whitespace +characters: + +.. code-block:: c++ + + #define SKIP_SPACES(p, limit) \ + { char *lim = (limit); \ + while (p < lim) { \ + if (*p++ != ' ') { \ + p--; break; }}} + +Here backslash-newline is used to split the macro definition, which must +be a single logical line, so that it resembles the way such code would +be laid out if not part of a macro definition. + +A call to this macro might be ``SKIP_SPACES (p, lim)``. Strictly +speaking, the call expands to a compound statement, which is a complete +statement with no need for a semicolon to end it. However, since it +looks like a function call, it minimizes confusion if you can use it +like a function call, writing a semicolon afterward, as in +``SKIP_SPACES (p, lim);`` + +This can cause trouble before ``else`` statements, because the +semicolon is actually a null statement. Suppose you write + +.. code-block:: c++ + + if (*p != 0) + SKIP_SPACES (p, lim); + else ... + +The presence of two statements---the compound statement and a null +statement---in between the ``if`` condition and the ``else`` +makes invalid C code. + +The definition of the macro ``SKIP_SPACES`` can be altered to solve +this problem, using a ``do ... while`` statement. Here is how: + +.. code-block:: c++ + + #define SKIP_SPACES(p, limit) \ + do { char *lim = (limit); \ + while (p < lim) { \ + if (*p++ != ' ') { \ + p--; break; }}} \ + while (0) + +Now ``SKIP_SPACES (p, lim);`` expands into + +.. code-block:: c++ + + do {...} while (0); + +which is one statement. The loop executes exactly once; most compilers +generate no extra code for it. + +.. index:: side effects (in macro arguments), unsafe macros + +.. _duplication-of-side-effects: + +Duplication of Side Effects +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Many C programs define a macro ``min``, for 'minimum', like this: + +.. code-block:: c++ + + #define min(X, Y) ((X) < (Y) ? (X) : (Y)) + +When you use this macro with an argument containing a side effect, +as shown here, + +.. code-block:: c++ + + next = min (x + y, foo (z)); + +it expands as follows: + +.. code-block:: c++ + + next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); + +where ``x + y`` has been substituted for ``X`` and ``foo (z)`` +for ``Y``. + +The function ``foo`` is used only once in the statement as it appears +in the program, but the expression ``foo (z)`` has been substituted +twice into the macro expansion. As a result, ``foo`` might be called +two times when the statement is executed. If it has side effects or if +it takes a long time to compute, the results might not be what you +intended. We say that ``min`` is an :dfn:`unsafe` macro. + +The best solution to this problem is to define ``min`` in a way that +computes the value of ``foo (z)`` only once. The C language offers +no standard way to do this, but it can be done with GNU extensions as +follows: + +.. code-block:: c++ + + #define min(X, Y) \ + ({ typeof (X) x_ = (X); \ + typeof (Y) y_ = (Y); \ + (x_ < y_) ? x_ : y_; }) + +The :samp:`({ ... })` notation produces a compound statement that +acts as an expression. Its value is the value of its last statement. +This permits us to define local variables and assign each argument to +one. The local variables have underscores after their names to reduce +the risk of conflict with an identifier of wider scope (it is impossible +to avoid this entirely). Now each argument is evaluated exactly once. + +If you do not wish to use GNU C extensions, the only solution is to be +careful when *using* the macro ``min``. For example, you can +calculate the value of ``foo (z)``, save it in a variable, and use +that variable in ``min`` : + +.. code-block:: c++ + + #define min(X, Y) ((X) < (Y) ? (X) : (Y)) + ... + { + int tem = foo (z); + next = min (x + y, tem); + } + +(where we assume that ``foo`` returns type ``int``). + +.. index:: self-reference + +.. _self-referential-macros: + +Self-Referential Macros +^^^^^^^^^^^^^^^^^^^^^^^ + +A :dfn:`self-referential` macro is one whose name appears in its +definition. Recall that all macro definitions are rescanned for more +macros to replace. If the self-reference were considered a use of the +macro, it would produce an infinitely large expansion. To prevent this, +the self-reference is not considered a macro call. It is passed into +the preprocessor output unchanged. Consider an example: + +.. code-block:: c++ + + #define foo (4 + foo) + +where ``foo`` is also a variable in your program. + +Following the ordinary rules, each reference to ``foo`` will expand +into ``(4 + foo)`` ; then this will be rescanned and will expand into +``(4 + (4 + foo))`` ; and so on until the computer runs out of memory. + +The self-reference rule cuts this process short after one step, at +``(4 + foo)``. Therefore, this macro definition has the possibly +useful effect of causing the program to add 4 to the value of ``foo`` +wherever ``foo`` is referred to. + +In most cases, it is a bad idea to take advantage of this feature. A +person reading the program who sees that ``foo`` is a variable will +not expect that it is a macro as well. The reader will come across the +identifier ``foo`` in the program and think its value should be that +of the variable ``foo``, whereas in fact the value is four greater. + +One common, useful use of self-reference is to create a macro which +expands to itself. If you write + +.. code-block:: c++ + + #define EPERM EPERM + +then the macro ``EPERM`` expands to ``EPERM``. Effectively, it is +left alone by the preprocessor whenever it's used in running text. You +can tell that it's a macro with :samp:`#ifdef`. You might do this if you +want to define numeric constants with an ``enum``, but have +:samp:`#ifdef` be true for each constant. + +If a macro ``x`` expands to use a macro ``y``, and the expansion of +``y`` refers to the macro ``x``, that is an :dfn:`indirect +self-reference` of ``x``. ``x`` is not expanded in this case +either. Thus, if we have + +.. code-block:: c++ + + #define x (4 + y) + #define y (2 * x) + +then ``x`` and ``y`` expand as follows: + +.. code-block:: + + x → (4 + y) + → (4 + (2 * x)) + + y → (2 * x) + → (2 * (4 + y)) + +Each macro is expanded when it appears in the definition of the other +macro, but not when it indirectly appears in its own definition. + +.. index:: expansion of arguments, macro argument expansion, prescan of macro arguments + +.. _argument-prescan: + +Argument Prescan +^^^^^^^^^^^^^^^^ + +Macro arguments are completely macro-expanded before they are +substituted into a macro body, unless they are stringized or pasted +with other tokens. After substitution, the entire macro body, including +the substituted arguments, is scanned again for macros to be expanded. +The result is that the arguments are scanned *twice* to expand +macro calls in them. + +Most of the time, this has no effect. If the argument contained any +macro calls, they are expanded during the first scan. The result +therefore contains no macro calls, so the second scan does not change +it. If the argument were substituted as given, with no prescan, the +single remaining scan would find the same macro calls and produce the +same results. + +You might expect the double scan to change the results when a +self-referential macro is used in an argument of another macro +(see :ref:`self-referential-macros`): the self-referential macro would be +expanded once in the first scan, and a second time in the second scan. +However, this is not what happens. The self-references that do not +expand in the first scan are marked so that they will not expand in the +second scan either. + +You might wonder, 'Why mention the prescan, if it makes no difference? +And why not skip it and make the preprocessor faster?' The answer is +that the prescan does make a difference in three special cases: + +* Nested calls to a macro. + + We say that :dfn:`nested` calls to a macro occur when a macro's argument + contains a call to that very macro. For example, if ``f`` is a macro + that expects one argument, ``f (f (1))`` is a nested pair of calls to + ``f``. The desired expansion is made by expanding ``f (1)`` and + substituting that into the definition of ``f``. The prescan causes + the expected result to happen. Without the prescan, ``f (1)`` itself + would be substituted as an argument, and the inner use of ``f`` would + appear during the main scan as an indirect self-reference and would not + be expanded. + +* Macros that call other macros that stringize or concatenate. + + If an argument is stringized or concatenated, the prescan does not + occur. If you *want* to expand a macro, then stringize or + concatenate its expansion, you can do that by causing one macro to call + another macro that does the stringizing or concatenation. For + instance, if you have + + .. code-block:: c++ + + #define AFTERX(x) X_ ## x + #define XAFTERX(x) AFTERX(x) + #define TABLESIZE 1024 + #define BUFSIZE TABLESIZE + + then ``AFTERX(BUFSIZE)`` expands to ``X_BUFSIZE``, and + ``XAFTERX(BUFSIZE)`` expands to ``X_1024``. (Not to + ``X_TABLESIZE``. Prescan always does a complete expansion.) + +* Macros used in arguments, whose expansions contain unshielded commas. + + This can cause a macro expanded on the second scan to be called with the + wrong number of arguments. Here is an example: + + .. code-block:: c++ + + #define foo a,b + #define bar(x) lose(x) + #define lose(x) (1 + (x)) + + We would like ``bar(foo)`` to turn into ``(1 + (foo))``, which + would then turn into ``(1 + (a,b))``. Instead, ``bar(foo)`` + expands into ``lose(a,b)``, and you get an error because ``lose`` + requires a single argument. In this case, the problem is easily solved + by the same parentheses that ought to be used to prevent misnesting of + arithmetic operations: + + .. code-block:: + + #define foo (a,b) + or#define bar(x) lose((x)) + + The extra pair of parentheses prevents the comma in ``foo`` 's + definition from being interpreted as an argument separator. + +.. index:: newlines in macro arguments + +.. _newlines-in-arguments: + +Newlines in Arguments +^^^^^^^^^^^^^^^^^^^^^ + +The invocation of a function-like macro can extend over many logical +lines. However, in the present implementation, the entire expansion +comes out on one line. Thus line numbers emitted by the compiler or +debugger refer to the line the invocation started on, which might be +different to the line containing the argument causing the problem. + +Here is an example illustrating this: + +.. code-block:: c++ + + #define ignore_second_arg(a,b,c) a; c + + ignore_second_arg (foo (), + ignored (), + syntax error); + +The syntax error triggered by the tokens ``syntax error`` results in +an error message citing line three---the line of ignore_second_arg--- +even though the problematic code comes from line five. + +We consider this a bug, and intend to fix it in the near future. \ No newline at end of file diff --git a/gcc/doc/cpp/macros/object-like-macros.rst b/gcc/doc/cpp/macros/object-like-macros.rst new file mode 100644 index 00000000000..c5e6e4cd466 --- /dev/null +++ b/gcc/doc/cpp/macros/object-like-macros.rst @@ -0,0 +1,126 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: object-like macro, symbolic constants, manifest constants + +.. _object-like-macros: + +Object-like Macros +****************** + +An :dfn:`object-like macro` is a simple identifier which will be replaced +by a code fragment. It is called object-like because it looks like a +data object in code that uses it. They are most commonly used to give +symbolic names to numeric constants. + +.. index:: #define + +You create macros with the :samp:`#define` directive. :samp:`#define` is +followed by the name of the macro and then the token sequence it should +be an abbreviation for, which is variously referred to as the macro's +:dfn:`body`, :dfn:`expansion` or :dfn:`replacement list`. For example, + +.. code-block:: c++ + + #define BUFFER_SIZE 1024 + +defines a macro named ``BUFFER_SIZE`` as an abbreviation for the +token ``1024``. If somewhere after this :samp:`#define` directive +there comes a C statement of the form + +.. code-block:: c++ + + foo = (char *) malloc (BUFFER_SIZE); + +then the C preprocessor will recognize and :dfn:`expand` the macro +``BUFFER_SIZE``. The C compiler will see the same tokens as it would +if you had written + +.. code-block:: c++ + + foo = (char *) malloc (1024); + +By convention, macro names are written in uppercase. Programs are +easier to read when it is possible to tell at a glance which names are +macros. + +The macro's body ends at the end of the :samp:`#define` line. You may +continue the definition onto multiple lines, if necessary, using +backslash-newline. When the macro is expanded, however, it will all +come out on one line. For example, + +.. code-block:: + + #define NUMBERS 1, \ + 2, \ + 3 + int x[] = { NUMBERS }; + → int x[] = { 1, 2, 3 }; + +The most common visible consequence of this is surprising line numbers +in error messages. + +There is no restriction on what can go in a macro body provided it +decomposes into valid preprocessing tokens. Parentheses need not +balance, and the body need not resemble valid C code. (If it does not, +you may get error messages from the C compiler when you use the macro.) + +The C preprocessor scans your program sequentially. Macro definitions +take effect at the place you write them. Therefore, the following input +to the C preprocessor + +.. code-block:: c++ + + foo = X; + #define X 4 + bar = X; + +produces + +.. code-block:: c++ + + foo = X; + bar = 4; + +When the preprocessor expands a macro name, the macro's expansion +replaces the macro invocation, then the expansion is examined for more +macros to expand. For example, + +.. code-block:: + + #define TABLESIZE BUFSIZE + #define BUFSIZE 1024 + TABLESIZE + → BUFSIZE + → 1024 + +``TABLESIZE`` is expanded first to produce ``BUFSIZE``, then that +macro is expanded to produce the final result, ``1024``. + +Notice that ``BUFSIZE`` was not defined when ``TABLESIZE`` was +defined. The :samp:`#define` for ``TABLESIZE`` uses exactly the +expansion you specify---in this case, ``BUFSIZE`` ---and does not +check to see whether it too contains macro names. Only when you +*use* ``TABLESIZE`` is the result of its expansion scanned for +more macro names. + +This makes a difference if you change the definition of ``BUFSIZE`` +at some point in the source file. ``TABLESIZE``, defined as shown, +will always expand using the definition of ``BUFSIZE`` that is +currently in effect: + +.. code-block:: c++ + + #define BUFSIZE 1020 + #define TABLESIZE BUFSIZE + #undef BUFSIZE + #define BUFSIZE 37 + +Now ``TABLESIZE`` expands (in two stages) to ``37``. + +If the expansion of a macro contains its own name, either directly or +via intermediate macros, it is not expanded again when the expansion is +examined for more macros. This prevents infinite recursion. +See :ref:`self-referential-macros`, for the precise details. \ No newline at end of file diff --git a/gcc/doc/cpp/macros/predefined-macros.rst b/gcc/doc/cpp/macros/predefined-macros.rst new file mode 100644 index 00000000000..8af566e0dc3 --- /dev/null +++ b/gcc/doc/cpp/macros/predefined-macros.rst @@ -0,0 +1,874 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: predefined macros + +.. _predefined-macros: + +Predefined Macros +***************** + +Several object-like macros are predefined; you use them without +supplying their definitions. They fall into three classes: standard, +common, and system-specific. + +In C++, there is a fourth category, the named operators. They act like +predefined macros, but you cannot undefine them. + +.. toctree:: + :maxdepth: 2 + + +.. index:: standard predefined macros. + +.. _standard-predefined-macros: + +Standard Predefined Macros +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The standard predefined macros are specified by the relevant +language standards, so they are available with all compilers that +implement those standards. Older compilers may not provide all of +them. Their names all start with double underscores. + +.. c:macro:: __FILE__ + + This macro expands to the name of the current input file, in the form of + a C string constant. This is the path by which the preprocessor opened + the file, not the short name specified in :samp:`#include` or as the + input file name argument. For example, + ``"/usr/local/include/myheader.h"`` is a possible expansion of this + macro. + +.. c:macro:: __LINE__ + + This macro expands to the current input line number, in the form of a + decimal integer constant. While we call it a predefined macro, it's + a pretty strange macro, since its 'definition' changes with each + new line of source code. + + ``__FILE__`` and ``__LINE__`` are useful in generating an error + message to report an inconsistency detected by the program; the message + can state the source line at which the inconsistency was detected. For + example, + +.. code-block:: c++ + + fprintf (stderr, "Internal error: " + "negative string length " + "%d at %s, line %d.", + length, __FILE__, __LINE__); + +An :samp:`#include` directive changes the expansions of ``__FILE__`` +and ``__LINE__`` to correspond to the included file. At the end of +that file, when processing resumes on the input file that contained +the :samp:`#include` directive, the expansions of ``__FILE__`` and +``__LINE__`` revert to the values they had before the +:samp:`#include` (but ``__LINE__`` is then incremented by one as +processing moves to the line after the :samp:`#include`). + +A :samp:`#line` directive changes ``__LINE__``, and may change +``__FILE__`` as well. See :ref:`line-control`. + +C99 introduced ``__func__``, and GCC has provided ``__FUNCTION__`` +for a long time. Both of these are strings containing the name of the +current function (there are slight semantic differences; see the GCC +manual). Neither of them is a macro; the preprocessor does not know the +name of the current function. They tend to be useful in conjunction +with ``__FILE__`` and ``__LINE__``, though. + +.. c:macro:: __DATE__ + + This macro expands to a string constant that describes the date on which + the preprocessor is being run. The string constant contains eleven + characters and looks like ``"Feb 12 1996"``. If the day of the + month is less than 10, it is padded with a space on the left. + + If GCC cannot determine the current date, it will emit a warning message + (once per compilation) and ``__DATE__`` will expand to + ``"??? ?? ????"``. + +.. c:macro:: __TIME__ + + This macro expands to a string constant that describes the time at + which the preprocessor is being run. The string constant contains + eight characters and looks like ``"23:59:01"``. + + If GCC cannot determine the current time, it will emit a warning message + (once per compilation) and ``__TIME__`` will expand to + ``"??:??:??"``. + +.. c:macro:: __STDC__ + + In normal operation, this macro expands to the constant 1, to signify + that this compiler conforms to ISO Standard C. If GNU CPP is used with + a compiler other than GCC, this is not necessarily true; however, the + preprocessor always conforms to the standard unless the + :option:`-traditional-cpp` option is used. + + This macro is not defined if the :option:`-traditional-cpp` option is used. + + On some hosts, the system compiler uses a different convention, where + ``__STDC__`` is normally 0, but is 1 if the user specifies strict + conformance to the C Standard. CPP follows the host convention when + processing system header files, but when processing user files + ``__STDC__`` is always 1. This has been reported to cause problems; + for instance, some versions of Solaris provide X Windows headers that + expect ``__STDC__`` to be either undefined or 1. See :ref:`invocation`. + +.. c:macro:: __STDC_VERSION__ + + This macro expands to the C Standard's version number, a long integer + constant of the form ``yyyymmL`` where :samp:`{yyyy}` and + :samp:`{mm}` are the year and month of the Standard version. This signifies + which version of the C Standard the compiler conforms to. Like + ``__STDC__``, this is not necessarily accurate for the entire + implementation, unless GNU CPP is being used with GCC. + + The value ``199409L`` signifies the 1989 C standard as amended in + 1994, which is the current default; the value ``199901L`` signifies + the 1999 revision of the C standard; the value ``201112L`` + signifies the 2011 revision of the C standard; the value + ``201710L`` signifies the 2017 revision of the C standard (which is + otherwise identical to the 2011 version apart from correction of + defects). An unspecified value larger than ``201710L`` is used for + the experimental :option:`-std=c2x` and :option:`-std=gnu2x` modes. + + This macro is not defined if the :option:`-traditional-cpp` option is + used, nor when compiling C++ or Objective-C. + +.. c:macro:: __STDC_HOSTED__ + + This macro is defined, with value 1, if the compiler's target is a + :dfn:`hosted environment`. A hosted environment has the complete + facilities of the standard C library available. + +.. c:macro:: __cplusplus + + This macro is defined when the C++ compiler is in use. You can use + ``__cplusplus`` to test whether a header is compiled by a C compiler + or a C++ compiler. This macro is similar to ``__STDC_VERSION__``, in + that it expands to a version number. Depending on the language standard + selected, the value of the macro is + ``199711L`` for the 1998 C++ standard, + ``201103L`` for the 2011 C++ standard, + ``201402L`` for the 2014 C++ standard, + ``201703L`` for the 2017 C++ standard, + ``202002L`` for the 2020 C++ standard, + or an unspecified value strictly larger than ``202002L`` for the + experimental languages enabled by :option:`-std=c++23` and + :option:`-std=gnu++23`. + +.. c:macro:: __OBJC__ + + This macro is defined, with value 1, when the Objective-C compiler is in + use. You can use ``__OBJC__`` to test whether a header is compiled + by a C compiler or an Objective-C compiler. + +.. c:macro:: __ASSEMBLER__ + + This macro is defined with value 1 when preprocessing assembly + language. + +.. index:: common predefined macros + +.. _common-predefined-macros: + +Common Predefined Macros +^^^^^^^^^^^^^^^^^^^^^^^^ + +The common predefined macros are GNU C extensions. They are available +with the same meanings regardless of the machine or operating system on +which you are using GNU C or GNU Fortran. Their names all start with +double underscores. + +.. c:macro:: __COUNTER__ + + This macro expands to sequential integral values starting from 0. In + conjunction with the ``##`` operator, this provides a convenient means to + generate unique identifiers. Care must be taken to ensure that + ``__COUNTER__`` is not expanded prior to inclusion of precompiled headers + which use it. Otherwise, the precompiled headers will not be used. + +.. c:macro:: __GFORTRAN__ + + The GNU Fortran compiler defines this. + +.. c:macro:: __GNUC__ + __GNUC_MINOR__ + __GNUC_PATCHLEVEL__ + + These macros are defined by all GNU compilers that use the C + preprocessor: C, C++, Objective-C and Fortran. Their values are the major + version, minor version, and patch level of the compiler, as integer + constants. For example, GCC version :samp:`{x}`. :samp:`{y}`. :samp:`{z}` + defines ``__GNUC__`` to :samp:`{x}`, ``__GNUC_MINOR__`` to :samp:`{y}`, + and ``__GNUC_PATCHLEVEL__`` to :samp:`{z}`. These + macros are also defined if you invoke the preprocessor directly. + + If all you need to know is whether or not your program is being compiled + by GCC, or a non-GCC compiler that claims to accept the GNU C dialects, + you can simply test ``__GNUC__``. If you need to write code + which depends on a specific version, you must be more careful. Each + time the minor version is increased, the patch level is reset to zero; + each time the major version is increased, the + minor version and patch level are reset. If you wish to use the + predefined macros directly in the conditional, you will need to write it + like this: + + .. code-block:: c++ + + /* Test for GCC > 3.2.0 */ + #if __GNUC__ > 3 || \ + (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \ + (__GNUC_MINOR__ == 2 && \ + __GNUC_PATCHLEVEL__ > 0)) + + Another approach is to use the predefined macros to + calculate a single number, then compare that against a threshold: + + .. code-block:: c++ + + #define GCC_VERSION (__GNUC__ * 10000 \ + + __GNUC_MINOR__ * 100 \ + + __GNUC_PATCHLEVEL__) + ... + /* Test for GCC > 3.2.0 */ + #if GCC_VERSION > 30200 + + Many people find this form easier to understand. + +.. c:macro:: __GNUG__ + + The GNU C++ compiler defines this. Testing it is equivalent to + testing ``(__GNUC__ && __cplusplus)``. + +.. c:macro:: __STRICT_ANSI__ + + GCC defines this macro if and only if the :option:`-ansi` switch, or a + :option:`-std` switch specifying strict conformance to some version of ISO C + or ISO C++, was specified when GCC was invoked. It is defined to :samp:`1`. + This macro exists primarily to direct GNU libc's header files to use only + definitions found in standard C. + +.. c:macro:: __BASE_FILE__ + + This macro expands to the name of the main input file, in the form + of a C string constant. This is the source file that was specified + on the command line of the preprocessor or C compiler. + +.. c:macro:: __FILE_NAME__ + + This macro expands to the basename of the current input file, in the + form of a C string constant. This is the last path component by which + the preprocessor opened the file. For example, processing + ``"/usr/local/include/myheader.h"`` would set this + macro to ``"myheader.h"``. + +.. c:macro:: __INCLUDE_LEVEL__ + + This macro expands to a decimal integer constant that represents the + depth of nesting in include files. The value of this macro is + incremented on every :samp:`#include` directive and decremented at the + end of every included file. It starts out at 0, its value within the + base file specified on the command line. + +.. c:macro:: __ELF__ + + This macro is defined if the target uses the ELF object format. + +.. c:macro:: __VERSION__ + + This macro expands to a string constant which describes the version of + the compiler in use. You should not rely on its contents having any + particular form, but it can be counted on to contain at least the + release number. + +.. c:macro:: __OPTIMIZE__ + __OPTIMIZE_SIZE__ + __NO_INLINE__ + + These macros describe the compilation mode. ``__OPTIMIZE__`` is + defined in all optimizing compilations. ``__OPTIMIZE_SIZE__`` is + defined if the compiler is optimizing for size, not speed. + ``__NO_INLINE__`` is defined if no functions will be inlined into + their callers (when not optimizing, or when inlining has been + specifically disabled by :option:`-fno-inline`). + + These macros cause certain GNU header files to provide optimized + definitions, using macros or inline functions, of system library + functions. You should not use these macros in any way unless you make + sure that programs will execute with the same effect whether or not they + are defined. If they are defined, their value is 1. + +.. c:macro:: __GNUC_GNU_INLINE__ + + GCC defines this macro if functions declared ``inline`` will be + handled in GCC's traditional gnu90 mode. Object files will contain + externally visible definitions of all functions declared ``inline`` + without ``extern`` or ``static``. They will not contain any + definitions of any functions declared ``extern inline``. + +.. c:macro:: __GNUC_STDC_INLINE__ + + GCC defines this macro if functions declared ``inline`` will be + handled according to the ISO C99 or later standards. Object files will contain + externally visible definitions of all functions declared ``extern + inline``. They will not contain definitions of any functions declared + ``inline`` without ``extern``. + + If this macro is defined, GCC supports the ``gnu_inline`` function + attribute as a way to always get the gnu90 behavior. + +.. c:macro:: __CHAR_UNSIGNED__ + + GCC defines this macro if and only if the data type ``char`` is + unsigned on the target machine. It exists to cause the standard header + file :samp:`limits.h` to work correctly. You should not use this macro + yourself; instead, refer to the standard macros defined in :samp:`limits.h`. + +.. c:macro:: __WCHAR_UNSIGNED__ + + Like ``__CHAR_UNSIGNED__``, this macro is defined if and only if the + data type ``wchar_t`` is unsigned and the front-end is in C++ mode. + +.. c:macro:: __REGISTER_PREFIX__ + + This macro expands to a single token (not a string constant) which is + the prefix applied to CPU register names in assembly language for this + target. You can use it to write assembly that is usable in multiple + environments. For example, in the ``m68k-aout`` environment it + expands to nothing, but in the ``m68k-coff`` environment it expands + to a single :samp:`%`. + +.. c:macro:: __USER_LABEL_PREFIX__ + + This macro expands to a single token which is the prefix applied to + user labels (symbols visible to C code) in assembly. For example, in + the ``m68k-aout`` environment it expands to an :samp:`_`, but in the + ``m68k-coff`` environment it expands to nothing. + + This macro will have the correct definition even if + :option:`-f(no-)underscores` is in use, but it will not be correct if + target-specific options that adjust this prefix are used (e.g. the + OSF/rose :option:`-mno-underscores` option). + +.. c:macro:: __SIZE_TYPE__ + __PTRDIFF_TYPE__ + __WCHAR_TYPE__ + __WINT_TYPE__ + __INTMAX_TYPE__ + __UINTMAX_TYPE__ + __SIG_ATOMIC_TYPE__ + __INT8_TYPE__ + __INT16_TYPE__ + __INT32_TYPE__ + __INT64_TYPE__ + __UINT8_TYPE__ + __UINT16_TYPE__ + __UINT32_TYPE__ + __UINT64_TYPE__ + __INT_LEAST8_TYPE__ + __INT_LEAST16_TYPE__ + __INT_LEAST32_TYPE__ + __INT_LEAST64_TYPE__ + __UINT_LEAST8_TYPE__ + __UINT_LEAST16_TYPE__ + __UINT_LEAST32_TYPE__ + __UINT_LEAST64_TYPE__ + __INT_FAST8_TYPE__ + __INT_FAST16_TYPE__ + __INT_FAST32_TYPE__ + __INT_FAST64_TYPE__ + __UINT_FAST8_TYPE__ + __UINT_FAST16_TYPE__ + __UINT_FAST32_TYPE__ + __UINT_FAST64_TYPE__ + __INTPTR_TYPE__ + __UINTPTR_TYPE__ + + These macros are defined to the correct underlying types for the + ``size_t``, ``ptrdiff_t``, ``wchar_t``, ``wint_t``, + ``intmax_t``, ``uintmax_t``, ``sig_atomic_t``, ``int8_t``, + ``int16_t``, ``int32_t``, ``int64_t``, ``uint8_t``, + ``uint16_t``, ``uint32_t``, ``uint64_t``, + ``int_least8_t``, ``int_least16_t``, ``int_least32_t``, + ``int_least64_t``, ``uint_least8_t``, ``uint_least16_t``, + ``uint_least32_t``, ``uint_least64_t``, ``int_fast8_t``, + ``int_fast16_t``, ``int_fast32_t``, ``int_fast64_t``, + ``uint_fast8_t``, ``uint_fast16_t``, ``uint_fast32_t``, + ``uint_fast64_t``, ``intptr_t``, and ``uintptr_t`` typedefs, + respectively. They exist to make the standard header files + :samp:`stddef.h`, :samp:`stdint.h`, and :samp:`wchar.h` work correctly. + You should not use these macros directly; instead, include the + appropriate headers and use the typedefs. Some of these macros may + not be defined on particular systems if GCC does not provide a + :samp:`stdint.h` header on those systems. + +.. c:macro:: __CHAR_BIT__ + + Defined to the number of bits used in the representation of the + ``char`` data type. It exists to make the standard header given + numerical limits work correctly. You should not use + this macro directly; instead, include the appropriate headers. + +.. c:macro::[...] [diff truncated at 524288 bytes]