From 8acae34b122a1a7152b95092688026aa83703cf5 Mon Sep 17 00:00:00 2001 From: Jeremy Retailleau Date: Sun, 20 Aug 2023 17:36:43 -0700 Subject: [PATCH] Update config to build and deploy documentation. - Add Doxygen config to build API documentation; - Add Sphinx config to build high-level documentation and installation guides; - Move content of Doxygen groups into Sphinx pages; - Add sphinxcontrib-doxylink to reference API doc symbols from Sphinx; - Add Github CI job to deploy documentation on Github Page; - Fix bug in vsnprintf.h to document ArchVStringPrintf. --- .github/workflows/docs-deploy.yml | 59 +++++++++++++ .github/workflows/linux.yml | 2 +- .github/workflows/macos.yml | 2 +- .github/workflows/windows.yml | 2 +- CMakeLists.txt | 9 ++ README.md | 5 ++ doc/CMakeLists.txt | 55 ++++++++++++ doc/doxygen/index.dox | 11 +++ doc/doxygen/namespaces.dox | 4 + doc/requirements.txt | 4 + doc/sphinx/_templates/breadcrumbs.html | 4 + doc/sphinx/api_reference/index.rst | 7 ++ doc/sphinx/bits.rst | 14 ++++ doc/sphinx/conf.py | 23 +++++ doc/sphinx/diagnostics.rst | 70 ++++++++++++++++ doc/sphinx/favicon.ico | Bin 0 -> 15406 bytes doc/sphinx/glossary.rst | 34 ++++++++ doc/sphinx/index.rst | 24 ++++++ doc/sphinx/installing.rst | 108 ++++++++++++++++++++++++ doc/sphinx/introduction.rst | 58 +++++++++++++ doc/sphinx/math.rst | 35 ++++++++ doc/sphinx/memory_management.rst | 42 ++++++++++ doc/sphinx/multithreading.rst | 23 +++++ doc/sphinx/strings.rst | 30 +++++++ doc/sphinx/symbol_visibility.rst | 14 ++++ doc/sphinx/system_functions.rst | 112 +++++++++++++++++++++++++ src/pxr/arch/align.h | 6 -- src/pxr/arch/daemon.h | 4 +- src/pxr/arch/demangle.h | 6 -- src/pxr/arch/env.h | 24 +----- src/pxr/arch/errno.h | 6 -- src/pxr/arch/error.h | 6 -- src/pxr/arch/export.h | 1 - src/pxr/arch/fileSystem.h | 6 -- src/pxr/arch/function.h | 1 - src/pxr/arch/inttypes.h | 1 - src/pxr/arch/library.h | 5 -- src/pxr/arch/mallocHook.h | 4 - src/pxr/arch/math.h | 7 -- src/pxr/arch/overview.dox | 94 --------------------- src/pxr/arch/stackTrace.h | 6 -- src/pxr/arch/symbols.h | 2 - src/pxr/arch/systemInfo.h | 6 -- src/pxr/arch/threads.h | 2 - src/pxr/arch/timing.h | 6 -- src/pxr/arch/virtualMemory.h | 1 - src/pxr/arch/vsnprintf.h | 8 +- 47 files changed, 752 insertions(+), 201 deletions(-) create mode 100644 .github/workflows/docs-deploy.yml create mode 100644 doc/CMakeLists.txt create mode 100644 doc/doxygen/index.dox create mode 100644 doc/doxygen/namespaces.dox create mode 100644 doc/requirements.txt create mode 100644 doc/sphinx/_templates/breadcrumbs.html create mode 100644 doc/sphinx/api_reference/index.rst create mode 100644 doc/sphinx/bits.rst create mode 100644 doc/sphinx/conf.py create mode 100644 doc/sphinx/diagnostics.rst create mode 100644 doc/sphinx/favicon.ico create mode 100644 doc/sphinx/glossary.rst create mode 100644 doc/sphinx/index.rst create mode 100644 doc/sphinx/installing.rst create mode 100644 doc/sphinx/introduction.rst create mode 100644 doc/sphinx/math.rst create mode 100644 doc/sphinx/memory_management.rst create mode 100644 doc/sphinx/multithreading.rst create mode 100644 doc/sphinx/strings.rst create mode 100644 doc/sphinx/symbol_visibility.rst create mode 100644 doc/sphinx/system_functions.rst delete mode 100644 src/pxr/arch/overview.dox diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml new file mode 100644 index 0000000..de693be --- /dev/null +++ b/.github/workflows/docs-deploy.yml @@ -0,0 +1,59 @@ +name: docs-deploy + +on: + push: + branches: [ main ] + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: macos-latest + + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.x" + + - name: Create Build Environment + working-directory: ${{runner.temp}} + run: | + brew install doxygen + python -m pip install --upgrade pip + python -m pip install -r ${{github.workspace}}/doc/requirements.txt + npm install https://github.com/jothepro/doxygen-awesome-css#v2.3.3 + cmake -E make_directory ${{github.workspace}}/build + + - name: Build documentation + working-directory: ${{github.workspace}}/build + run: | + cmake \ + -D "BUILD_TESTS=OFF" \ + -D "DOXYGEN_HTML_EXTRA_STYLESHEET=${{runner.temp}}/node_modules/@jothepro/doxygen-awesome-css/doxygen-awesome.css" .. + cmake --build . --target documentation + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ${{github.workspace}}/build/doc/doc/pxr/arch + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + runs-on: macos-latest + needs: build + + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml index 65ea101..aa3ef37 100644 --- a/.github/workflows/linux.yml +++ b/.github/workflows/linux.yml @@ -31,7 +31,7 @@ jobs: - name: Configure working-directory: ${{github.workspace}}/build - run: cmake .. + run: cmake -D "BUILD_DOCS=OFF" .. - name: Build working-directory: ${{github.workspace}}/build diff --git a/.github/workflows/macos.yml b/.github/workflows/macos.yml index 3fe875d..458384f 100644 --- a/.github/workflows/macos.yml +++ b/.github/workflows/macos.yml @@ -30,7 +30,7 @@ jobs: - name: Configure working-directory: ${{github.workspace}}/build - run: cmake .. + run: cmake -D "BUILD_DOCS=OFF" .. - name: Build working-directory: ${{github.workspace}}/build diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.yml index d09678e..e1a06dc 100644 --- a/.github/workflows/windows.yml +++ b/.github/workflows/windows.yml @@ -32,7 +32,7 @@ jobs: - name: Configure working-directory: ${{github.workspace}}/build - run: cmake -D "ENABLE_PRECOMPILED_HEADERS=ON" .. + run: cmake -D "BUILD_DOCS=OFF" -D "ENABLE_PRECOMPILED_HEADERS=ON" .. - name: Build working-directory: ${{github.workspace}}/build diff --git a/CMakeLists.txt b/CMakeLists.txt index 603406f..e88e597 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -19,6 +19,7 @@ set(CMAKE_CXX_EXTENSIONS OFF) # Default options. option(BUILD_TESTS "Build tests" ON) +option(BUILD_DOCS "Build documentation" ON) option(BUILD_SHARED_LIBS "Build Shared Library" ON) option(ENABLE_PRECOMPILED_HEADERS "Enable precompiled headers." OFF) @@ -58,6 +59,14 @@ if (BUILD_TESTS) add_subdirectory(test) endif() +# Build documentation if required. +if (BUILD_DOCS) + find_package(Sphinx 1.8.6 REQUIRED) + find_package(Doxygen 1.8.5 REQUIRED) + + add_subdirectory(doc) +endif() + include(CMakePackageConfigHelpers) configure_package_config_file( diff --git a/README.md b/README.md index 16535ba..2989e72 100644 --- a/README.md +++ b/README.md @@ -17,3 +17,8 @@ It is regularly rebased over the "release" branch of the original explicit divergence information from the latest updates and is currently synchronized with [v25.02](https://github.com/PixarAnimationStudios/OpenUSD/releases/tag/v25.02). + +## Documentation + +Full documentation, including installation and setup guides, can be found at +https://untwine.github.io/pxr-arch/ diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt new file mode 100644 index 0000000..e6f7a0a --- /dev/null +++ b/doc/CMakeLists.txt @@ -0,0 +1,55 @@ +file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/doc/pxr/arch") + +set(DOXYGEN_PROJECT_NAME "Pixar Arch") +set(DOXYGEN_PROJECT_ICON "${PROJECT_SOURCE_DIR}/doc/sphinx/favicon.ico") +set(DOXYGEN_HTML_OUTPUT "doc/pxr/arch/doxygen") +set(DOXYGEN_EXTENSION_MAPPING "h=C++") +set(DOXYGEN_GENERATE_HTML YES) +set(DOXYGEN_GENERATE_LATEX NO) +set(DOXYGEN_GENERATE_TREEVIEW YES) +set(DOXYGEN_QUIET YES) +set(DOXYGEN_SORT_MEMBER_DOCS NO) +set(DOXYGEN_FULL_PATH_NAMES NO) +set(DOXYGEN_FILE_PATTERNS *.dox *.h) +set(DOXYGEN_ALWAYS_DETAILED_SEC YES) +set(DOXYGEN_JAVADOC_AUTOBRIEF YES) +set(DOXYGEN_BUILTIN_STL_SUPPORT YES) +set(DOXYGEN_INLINE_SIMPLE_STRUCTS YES) +set(DOXYGEN_PREDEFINED doxygen) +set(DOXYGEN_QUIET YES) +set(DOXYGEN_EXTRACT_ALL YES) +set(DOXYGEN_WARN_IF_DOC_ERROR NO) +set(DOXYGEN_EXCLUDE + "${PROJECT_SOURCE_DIR}/src/pxr/arch/api.h" + "${PROJECT_SOURCE_DIR}/src/pxr/arch/pch.h" +) +set(DOXYGEN_GENERATE_TAGFILE + "${CMAKE_CURRENT_BINARY_DIR}/doc/pxr/arch/pxr-arch.tag") + +doxygen_add_docs(archApiRefDoc + "${PROJECT_SOURCE_DIR}/doc/doxygen/index.dox" + "${PROJECT_SOURCE_DIR}/doc/doxygen/namespaces.dox" + "${PROJECT_SOURCE_DIR}/src/pxr/arch" +) + +file(COPY sphinx DESTINATION ${CMAKE_CURRENT_BINARY_DIR}) +configure_file(sphinx/conf.py sphinx/conf.py @ONLY) + +sphinx_add_docs(archDoc + SOURCE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/sphinx" + OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/doc/pxr/arch" + DEPENDS archApiRefDoc +) + +add_custom_target(documentation ALL) +add_dependencies(documentation + archDoc + archApiRefDoc +) + +install( + DIRECTORY + "${CMAKE_CURRENT_BINARY_DIR}/doc" + DESTINATION + ${CMAKE_INSTALL_PREFIX} +) diff --git a/doc/doxygen/index.dox b/doc/doxygen/index.dox new file mode 100644 index 0000000..caff4c1 --- /dev/null +++ b/doc/doxygen/index.dox @@ -0,0 +1,11 @@ +/*! +\mainpage Home + +Abstract architecture-dependent logic. + +Read the [documentation](../index.html), or explore [the API](\ref pxr). + +
+ +Copyright 2024, Pixar, modified by Jeremy Retailleau +*/ diff --git a/doc/doxygen/namespaces.dox b/doc/doxygen/namespaces.dox new file mode 100644 index 0000000..2498b32 --- /dev/null +++ b/doc/doxygen/namespaces.dox @@ -0,0 +1,4 @@ +/*! +\namespace pxr +Scope of the Pixar libraries. +*/ diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..5a76593 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,4 @@ +Sphinx==7.4.7 +sphinx-cmake==0.2.1 +sphinx-rtd-theme==2.0.0 +sphinxcontrib-doxylink==1.12.3 diff --git a/doc/sphinx/_templates/breadcrumbs.html b/doc/sphinx/_templates/breadcrumbs.html new file mode 100644 index 0000000..4ecb013 --- /dev/null +++ b/doc/sphinx/_templates/breadcrumbs.html @@ -0,0 +1,4 @@ +{%- extends "sphinx_rtd_theme/breadcrumbs.html" %} + +{% block breadcrumbs_aside %} +{% endblock %} diff --git a/doc/sphinx/api_reference/index.rst b/doc/sphinx/api_reference/index.rst new file mode 100644 index 0000000..796e79b --- /dev/null +++ b/doc/sphinx/api_reference/index.rst @@ -0,0 +1,7 @@ +.. _api_reference: + +************* +API Reference +************* + +* `C++ API Documentation <../doxygen/index.html>`_ diff --git a/doc/sphinx/bits.rst b/doc/sphinx/bits.rst new file mode 100644 index 0000000..8032039 --- /dev/null +++ b/doc/sphinx/bits.rst @@ -0,0 +1,14 @@ +.. _bits: + +**** +Bits +**** + +Functions having to do with how bits are laid out on a machine. + +.. _bits/files: + +Files +~~~~~ + +* :arch-cpp:`inttypes.h` diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py new file mode 100644 index 0000000..85723b1 --- /dev/null +++ b/doc/sphinx/conf.py @@ -0,0 +1,23 @@ +"""Arch documentation build configuration file.""" + +import pathlib + +# -- General ------------------------------------------------------------------ + +extensions = ["sphinxcontrib.doxylink"] +templates_path = ["_templates"] +source_suffix = ".rst" +master_doc = "index" + +project = "Pixar Arch" +copyright = "2024, Pixar, modified by Jeremy Retailleau" + +build_path = pathlib.Path("@CMAKE_CURRENT_BINARY_DIR@/doc/pxr/arch") +doxylink = {"arch-cpp": ((build_path / "pxr-arch.tag").as_posix(), "./doxygen")} +add_function_parentheses = True + +# -- HTML output -------------------------------------------------------------- + +html_theme = "sphinx_rtd_theme" +html_favicon = "favicon.ico" +html_show_sphinx = False diff --git a/doc/sphinx/diagnostics.rst b/doc/sphinx/diagnostics.rst new file mode 100644 index 0000000..c8c9e9e --- /dev/null +++ b/doc/sphinx/diagnostics.rst @@ -0,0 +1,70 @@ +.. _diagnostics: + +*********** +Diagnostics +*********** + +Functions having to do with error reporting/handling. + +.. _diagnostics/files: + +Files +~~~~~ + +* :arch-cpp:`error.h` +* :arch-cpp:`stackTrace.h` +* :arch-cpp:`symbols.h` + +.. _diagnostics/macros: + +Macros +~~~~~~ + +* :arch-cpp:`ARCH_ERROR` +* :arch-cpp:`ARCH_WARNING` +* :arch-cpp:`ARCH_AXIOM` + +.. _diagnostics/typedefs: + +Typedefs +~~~~~~~~ + +* :arch-cpp:`ArchStackTraceCallback` +* :arch-cpp:`ArchCrashHandlerSystemCB` + +.. _diagnostics/functions: + +Functions +~~~~~~~~~ + +* :arch-cpp:`ArchLogFatalProcessState` +* :arch-cpp:`ArchLogCurrentProcessState` +* :arch-cpp:`ArchSetProcessStateLogCommand` +* :arch-cpp:`ArchIsAppCrashing` +* :arch-cpp:`ArchLogSessionInfo` +* :arch-cpp:`ArchSetLogSession` +* :arch-cpp:`ArchEnableSessionLogging` +* :arch-cpp:`ArchPrintStackTrace(FILE*, const std::string&, const std::string&)` +* :arch-cpp:`ArchPrintStackTrace(FILE*, const std::string&)` +* :arch-cpp:`ArchPrintStackTrace(std::ostream&, const std::string&, const std::string&)` +* :arch-cpp:`ArchPrintStackTrace(std::ostream&, const std::string&)` +* :arch-cpp:`ArchSetStackTraceCallback` +* :arch-cpp:`ArchGetStackTraceCallback` +* :arch-cpp:`ArchGetAppLaunchTime` +* :arch-cpp:`ArchSetFatalStackLogging` +* :arch-cpp:`ArchGetFatalStackLogging` +* :arch-cpp:`ArchSetProgramNameForErrors` +* :arch-cpp:`ArchGetProgramNameForErrors` +* :arch-cpp:`ArchSetProgramInfoForErrors` +* :arch-cpp:`ArchGetProgramInfoForErrors` +* :arch-cpp:`ArchSetExtraLogInfoForErrors` +* :arch-cpp:`ArchLogStackTrace(const std::string&, const std::string&, bool = false, const std::string& = "")` +* :arch-cpp:`ArchLogStackTrace(const std::string&, bool = false, const std::string& = "")` +* :arch-cpp:`ArchGetStackTrace` +* :arch-cpp:`ArchGetStackFrames(size_t, std::vector< uintptr_t >*)` +* :arch-cpp:`ArchGetStackFrames(size_t, uintptr_t*)` +* :arch-cpp:`ArchGetStackFrames(size_t, size_t, std::vector< uintptr_t >*)` +* :arch-cpp:`ArchGetStackFrames(size_t, size_t, uintptr_t*)` +* :arch-cpp:`ArchPrintStackFrames` +* :arch-cpp:`ArchCrashHandlerSystemv` +* :arch-cpp:`ArchGetAddressInfo` diff --git a/doc/sphinx/favicon.ico b/doc/sphinx/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..a973876a69d814992ae5cd14f64649298c52ba0d GIT binary patch literal 15406 zcmeI3<*yaV62RwW-yg91VZRgf;um+9Ai>=o76=3lPSBvi-2wy)?j9_-26uONmwM+{ z`}(Bsxija?y_ek$%TzL)xzp9%Rn^s1)m4q-{Kxsl`Sn*P^qb20+E?lR0x{;YkXAW5$e;7A;!H zqD713>({UP@U3_6-qNjGx0qv1o;+DTeflKJmoJwZHEKw`diCVs!GrSR#S7`%x38p4 zo7QuT9zA-<>C>mBTD59&`}S?czjp1K9654CiWMs+*RNlfL4yXl_D`Qaz1+WlUxo}B zqU||z=9FE#cFEDBN5eAc)vK30d-hB+Wy+Ljj7pU%$+vIcBu9=M+E%MpE&2TUvkV?Q zSaRjcrQhiH@#9CSTeoha{tX&5(6)5x(rMeoi4$e#&Yg1j@L_4(xN#UCIkaxwI{dd; z8|HZb{=IbW+*#X(4<9ZA2M$#Emnl<5ztIob7A#mWQGdo6FkpbTZ`!m;)~s10@7}$W zdGqGUtXZ>U{rdGv->6ZeT>Bb2;BCQz1+sYYVrkW?m6R=8R&`xqjPXuf0y|&o=qD719w>%9Sh9q)8L?!Mxi*Jg{WR z63Le@pG=xGN&O4onl^2kVjA!_@CYy_f9KDiU;TZD4jqJtxTH#zDq_=xKdf1^W{Tz~ zCV?m7k0(!_C=JkZ=FAx>T)1#}>@HopD9<3!zHi??sZgPUu3Lr-8NzseWp40@FBM`_-^eY<|2K7D$!<}Y5nc$g=2D{I!Q z8l#OHH%`YT?(5X4lYIH|MdyC-;DN3Iv_ls%0B9#}Gd%hIUAAnQ%96OMeEIST`lE-$ zAMgt>cd1gP65y~0kR7ml_wEF3v1rJiJ$sn;>afvtG+TFgPv%u4*PZRYajwV(IIExS$1IWQ`tP2+| zX#1*Ft6baN`iveuTKix_BF{{gnF0;>gpFe-T>-g{=t=(;Y&IJJduq`$Yc8>3R z_wE(;DEk8#F=9jlJo+?j*idn4_j5)w^Po#NZ{DPvK!54drNd)$=HT3iUF7@*px-tQ z<6y6@ht6dH>&2cjEFM>REXjO((ZYJ7Pv|CgB@&NVh&F6dks?JBwMXIy ze|yK4foy&r*?8pzewOd#NkS=Fr)lU3@+3cx-Ul`=SnEIs0v!l+AkcvyRR_q8a2Dc> zMop7%|aIBLT}u-p?XO^mzsoMy8Pfl2el+q>wy+(J?ukl z20DHI{CTAv`pJ!wr;MbXHgcZS>d+_Vu2`|6JbwJxEQ`E;{aSkV>>0Mre&~yZ!`&8Y zM9dFB|Fmh-!uAgSu&aj-9nv=L%#gp|8M=>R_BwrEzI>^7Z0x!wJ_Oro^3C9pW5gE3 zqRVeP^+N8t0F2MtlV>IuYmb5L!QMdM`0?X~8jJyIKID7d_BMBT@F|8@cQN}GXTxlckT|LgMMn(#1RJY3ET;Y#&fhb_7C+G1JrV& z;bRAlokD-9(_;q>O~;QPk7?Jjxdyn?=vGsSMuXjk9YlW(P!G4;?RVB{>eQ*>wZezt z6S${nc*3Tb`;K;B``y+*j}4s~zoZ_xh}noIxl3*0G3e)=`#IQN;!bdRkOB91*<-feP*=C_ zASZ`ryASgcd)a3$cz`bAX7qIP=FPhP#A$|4Xh){RX6#$;6+tVw>~G>s?kwB*oG-?X z9UC*=u<7&j&RTZw-aUbTguZBiOgC=asOMVbY~nMoKG-+%E9jpenv#RVT?uj^tg$UO znoS#JYj3vwQHy6Rdnarv15X7CC=t-$^RQ*ubOxb zJBmH!E)IMD#EBD%zhlP^z3)yu?&Vkf(34yo_64ytwvq?FqQ%L?V&K^LDT&XLOLx#O c$jt{j5a>Xl1Az|w(>f5k9uz + glossary diff --git a/doc/sphinx/installing.rst b/doc/sphinx/installing.rst new file mode 100644 index 0000000..3076de9 --- /dev/null +++ b/doc/sphinx/installing.rst @@ -0,0 +1,108 @@ +.. _installing: + +********** +Installing +********** + +.. highlight:: bash + +The library can be installed using :term:`CMake` (any version over `3.21 +`_). + +.. _installing/dependencies: + +Dependencies +============ + +Custom search paths to dependent packages can be provided with the following +:term:`CMake` options (or environment variable): + +============================= ========================================================= +Option / Environment Variable Description +============================= ========================================================= +Doxygen_ROOT Add search path to :term:`doxygen` program. +Sphinx_ROOT Add search path to :term:`sphinx-build ` program. +============================= ========================================================= + +.. note:: + + These feature is provided by :term:`CMake` under the `CMP0074 + `_ policy + +.. _installing/building: + +Building library +================ + +Obtain a copy of the source by either downloading the +`zipball `_ or +cloning the public repository:: + + git clone git@github.com:untwine/pxr-arch.git + +Then you can build and install the library as follows:: + + cd arch + cmake -DCMAKE_INSTALL_PREFIX=/path/to/destination -S . -B ./build .. + cmake --build ./build --target install + +Here are a few :term:`CMake` options that can be used to influence the building +process: + +========================== ================================================================= +Option Description +========================== ================================================================= +BUILD_TESTS Indicate whether tests should be built. Default is true. +BUILD_DOCS Indicate whether documentation should be built. Default is true. +BUILD_SHARED_LIBS Indicate whether library should be built shared. Default is true. +CMAKE_CXX_STANDARD Indicate the C++ standard requested. Default is C++ 17. +ENABLE_PRECOMPILED_HEADERS Support pre-compiled headers. Default is false. +========================== ================================================================= + +The build type can be influenced by the `CMAKE_BUILD_TYPE +`_ option or +environment variable. By default, the "Release" build type will be used. + +The library can then be used by other programs or libraries via the following +:term:`Cmake` target: + +* ``pxr::arch`` + +.. _installing/documentation: + +Building documentation +====================== + +Ensure that :term:`Doxygen` is installed. The required Python dependencies +must also be installed as follows:: + + pip install -r doc/requirements.txt + +Then build the documentation as follows:: + + cmake --build ./build --target documentation + +.. note:: + + The documentation built by default, unless you set the ``BUILD_DOCS`` + :term:`CMake` option to false. + +.. _installing/test: + +Running tests +============= + +Once the library and all tests are built, you can run the tests using +:term:`Ctest` within the build folder as follows:: + + ctest + +You can increase the verbosity and filter in one or several tests as follows:: + + ctest -VV + ctest -R testArchDemangle -VV + +.. note:: + + The tests are built by default, unless you set the ``BUILD_TESTS`` + :term:`CMake` option to false. diff --git a/doc/sphinx/introduction.rst b/doc/sphinx/introduction.rst new file mode 100644 index 0000000..da6047d --- /dev/null +++ b/doc/sphinx/introduction.rst @@ -0,0 +1,58 @@ +.. _introduction: + +************ +Introduction +************ + +The arch library is a repository for all architecture-dependent code. It +isolates all platform dependencies (and confusing #ifdefs) into one small +library and also serves as a common area for documentation of these +multi-platform issues. + +The high-level grouping of the classes/functions is: + +* :ref:`bits` +* :ref:`multithreading` +* :ref:`math` +* :ref:`strings` +* :ref:`system_functions` +* :ref:`memory_management` +* :ref:`diagnostics` +* :ref:`symbol_visibility` + +Symbols for use within ``libarch``: + +For OS: + +* ``ARCH_OS_LINUX`` +* ``ARCH_OS_DARWIN`` +* ``ARCH_OS_WINDOWS`` + +For processor: + +* ``ARCH_CPU_INTEL`` +* ``ARCH_CPU_ARM`` + +For bits: + +* ``ARCH_BITS_64`` + +For compiler: + +* ``ARCH_COMPILER_CLANG`` + + * ``ARCH_COMPILER_CLANG_MAJOR`` + * ``ARCH_COMPILER_CLANG_MINOR`` + * ``ARCH_COMPILER_CLANG_PATCHLEVEL`` + +* ``ARCH_COMPILER_GCC`` + + * ``ARCH_COMPILER_GCC_MAJOR`` + * ``ARCH_COMPILER_GCC_MINOR`` + * ``ARCH_COMPILER_GCC_PATCHLEVEL`` + +* ``ARCH_COMPILER_MSVC`` + + * ``ARCH_COMPILER_MSVC_VERSION`` + +* ``ARCH_COMPILER_ICC`` diff --git a/doc/sphinx/math.rst b/doc/sphinx/math.rst new file mode 100644 index 0000000..9809857 --- /dev/null +++ b/doc/sphinx/math.rst @@ -0,0 +1,35 @@ +.. _math: + +**** +Math +**** + +Functions for math. + +.. _math/files: + +Files +~~~~~ + +* :arch-cpp:`math.h` + +.. _math/macros: + +Macros +~~~~~~ + +* :arch-cpp:`ARCH_MIN_FLOAT_EPS_SQR` + +.. _math/functions: + +Functions +~~~~~~~~~ + +* :arch-cpp:`ArchSign` +* :arch-cpp:`ArchFloatToBitPattern` +* :arch-cpp:`ArchBitPatternToFloat` +* :arch-cpp:`ArchDoubleToBitPattern` +* :arch-cpp:`ArchBitPatternToDouble` +* :arch-cpp:`ArchSinCosf` +* :arch-cpp:`ArchSinCos` +* :arch-cpp:`ArchCountTrailingZeros` diff --git a/doc/sphinx/memory_management.rst b/doc/sphinx/memory_management.rst new file mode 100644 index 0000000..1317b06 --- /dev/null +++ b/doc/sphinx/memory_management.rst @@ -0,0 +1,42 @@ +.. _memory_management: + +***************** +Memory Management +***************** + +Functions having to do with memory allocation/handling + +.. _memory_management/files: + +Files +~~~~~ + +* :arch-cpp:`align.h` +* :arch-cpp:`mallocHook.h` + +.. _memory_management/classes: + +Classes +~~~~~~~ + +* :arch-cpp:`ArchMallocHook` + +.. _memory_management/macros: + +Macros +~~~~~~ + +* :arch-cpp:`ARCH_MAX_ALIGNMENT_INCREASE` +* :arch-cpp:`ARCH_CACHE_LINE_SIZE` + +.. _memory_management/functions: + +Functions +~~~~~~~~~ + +* :arch-cpp:`ArchAlignMemorySize` +* :arch-cpp:`ArchAlignMemory` +* :arch-cpp:`ArchAlignedAlloc` +* :arch-cpp:`ArchAlignedFree` +* :arch-cpp:`ArchIsPtmallocActive` +* :arch-cpp:`ArchIsStlAllocatorOff` diff --git a/doc/sphinx/multithreading.rst b/doc/sphinx/multithreading.rst new file mode 100644 index 0000000..3bd726f --- /dev/null +++ b/doc/sphinx/multithreading.rst @@ -0,0 +1,23 @@ +.. _multithreading: + +************** +Multithreading +************** + +Functions having to do with multithreading. + +.. _multithreading/files: + +Files +~~~~~ + +* :arch-cpp:`daemon.h` +* :arch-cpp:`threads.h` + +.. _multithreading/functions: + +Functions +~~~~~~~~~ + +* :arch-cpp:`ArchCloseAllFiles` +* :arch-cpp:`ArchIsMainThread` diff --git a/doc/sphinx/strings.rst b/doc/sphinx/strings.rst new file mode 100644 index 0000000..b2d3bdc --- /dev/null +++ b/doc/sphinx/strings.rst @@ -0,0 +1,30 @@ +.. _strings: + +******* +Strings +******* + +Functions having to do with string massaging/manipulation + +.. _strings/files: + +Files +~~~~~ + +* :arch-cpp:`demangle.h` +* :arch-cpp:`vsnprintf.h` + +.. _strings/functions: + +Functions +~~~~~~~~~ + +* :arch-cpp:`ArchDemangle` +* :arch-cpp:`ArchGetDemangled(const std::string&)` +* :arch-cpp:`ArchGetDemangled(const char*)` +* :arch-cpp:`ArchGetDemangled(const std::type_info&)` +* :arch-cpp:`ArchGetDemangled(const std::type_index&)` +* :arch-cpp:`ArchGetDemangled()` +* :arch-cpp:`ArchVsnprintf` +* :arch-cpp:`ArchStringPrintf` +* :arch-cpp:`ArchVStringPrintf` diff --git a/doc/sphinx/symbol_visibility.rst b/doc/sphinx/symbol_visibility.rst new file mode 100644 index 0000000..dec3521 --- /dev/null +++ b/doc/sphinx/symbol_visibility.rst @@ -0,0 +1,14 @@ +.. _symbol_visibility: + +***************** +Symbol Visibility +***************** + +Macros having to do with symbol visibility + +.. _symbol_visibility/files: + +Files +~~~~~ + +* :arch-cpp:`export.h` diff --git a/doc/sphinx/system_functions.rst b/doc/sphinx/system_functions.rst new file mode 100644 index 0000000..60b1fe0 --- /dev/null +++ b/doc/sphinx/system_functions.rst @@ -0,0 +1,112 @@ +.. _system_functions: + +**************** +System Functions +**************** + +Functions that encapsulate differing low-level system calls. + +.. _system_functions/files: + +Files +~~~~~ + +* :arch-cpp:`errno.h` +* :arch-cpp:`fileSystem.h` +* :arch-cpp:`systemInfo.h` +* :arch-cpp:`timing.h` +* :arch-cpp:`virtualMemory.h` + +.. _system_functions/classes: + +Classes +~~~~~~~ + +* :arch-cpp:`ArchIntervalTimer` + +.. _system_functions/macros: + +Macros +~~~~~~ + +* :arch-cpp:`ARCH_GLOB_NOCHECK` +* :arch-cpp:`ARCH_GLOB_MARK` +* :arch-cpp:`ARCH_GLOB_NOSORT` +* :arch-cpp:`ARCH_GLOB_DEFAULT` +* :arch-cpp:`ARCH_PATH_MAX` +* :arch-cpp:`ARCH_PATH_SEP` +* :arch-cpp:`ARCH_PATH_LIST_SEP` +* :arch-cpp:`ARCH_REL_PATH_IDENT` + +.. _system_functions/typedefs: + +Typedefs +~~~~~~~~ + +* :arch-cpp:`ArchStatType` +* :arch-cpp:`ArchConstFileMapping` +* :arch-cpp:`ArchMutableFileMapping` + +.. _system_functions/enumerations: + +Enumerations +~~~~~~~~~~~~ + +* :arch-cpp:`ArchMemAdvice` +* :arch-cpp:`ArchFileAdvice` + +.. _system_functions/functions: + +Functions +~~~~~~~~~ + +* :arch-cpp:`ArchHasEnv` +* :arch-cpp:`ArchGetEnv` +* :arch-cpp:`ArchSetEnv` +* :arch-cpp:`ArchRemoveEnv` +* :arch-cpp:`ArchExpandEnvironmentVariables` +* :arch-cpp:`ArchStrerror()` +* :arch-cpp:`ArchStrerror(int)` +* :arch-cpp:`ArchOpenFile` +* :arch-cpp:`ArchGetFileLength(const char*)` +* :arch-cpp:`ArchGetFileLength(FILE*)` +* :arch-cpp:`ArchGetFileName` +* :arch-cpp:`ArchStatIsWritable` +* :arch-cpp:`ArchGetModificationTime(const char*, double*)` +* :arch-cpp:`ArchGetModificationTime(const ArchStatType&)` +* :arch-cpp:`ArchNormPath` +* :arch-cpp:`ArchAbsPath` +* :arch-cpp:`ArchGetStatMode` +* :arch-cpp:`ArchGetTmpDir` +* :arch-cpp:`ArchMakeTmpFileName` +* :arch-cpp:`ArchMakeTmpFile(const std::string&, std::string* = nullptr)` +* :arch-cpp:`ArchMakeTmpFile(const std::string&, const std::string&, std::string* = nullptr)` +* :arch-cpp:`ArchMakeTmpSubdir` +* :arch-cpp:`ArchGetFileMappingLength(ArchConstFileMapping const &)` +* :arch-cpp:`ArchGetFileMappingLength(ArchMutableFileMapping const &)` +* :arch-cpp:`ArchMapFileReadOnly(FILE*, std::string* = nullptr)` +* :arch-cpp:`ArchMapFileReadOnly(std::string const &, std::string* = nullptr)` +* :arch-cpp:`ArchMapFileReadWrite(FILE*, std::string* = nullptr)` +* :arch-cpp:`ArchMapFileReadWrite(std::string const &, std::string* = nullptr)` +* :arch-cpp:`ArchMemAdvise` +* :arch-cpp:`ArchQueryMappedMemoryResidency` +* :arch-cpp:`ArchPRead` +* :arch-cpp:`ArchPWrite` +* :arch-cpp:`ArchReadLink` +* :arch-cpp:`ArchFileAdvise` +* :arch-cpp:`ArchLibraryOpen` +* :arch-cpp:`ArchLibraryError` +* :arch-cpp:`ArchLibraryClose` +* :arch-cpp:`ArchLibraryGetSymbolAddress` +* :arch-cpp:`ArchGetCwd` +* :arch-cpp:`ArchGetExecutablePath` +* :arch-cpp:`ArchGetPageSize` +* :arch-cpp:`ArchGetTickTime` +* :arch-cpp:`ArchGetStartTickTime` +* :arch-cpp:`ArchGetStopTickTime` +* :arch-cpp:`ArchGetTickQuantum` +* :arch-cpp:`ArchGetIntervalTimerTickOverhead` +* :arch-cpp:`ArchTicksToNanoseconds` +* :arch-cpp:`ArchTicksToSeconds` +* :arch-cpp:`ArchSecondsToTicks` +* :arch-cpp:`ArchMeasureExecutionTime` diff --git a/src/pxr/arch/align.h b/src/pxr/arch/align.h index 5b2d577..55a39ed 100644 --- a/src/pxr/arch/align.h +++ b/src/pxr/arch/align.h @@ -9,7 +9,6 @@ #define PXR_ARCH_ALIGN_H /// \file arch/align.h -/// \ingroup group_arch_Memory /// Provide architecture-specific memory-alignment information. #if !defined(__cplusplus) @@ -23,9 +22,6 @@ namespace pxr { -/// \addtogroup group_arch_Memory -///@{ - /// Return suitably aligned memory size. /// /// Requests to \c malloc() or \c ::new for a given size are often rounded @@ -77,8 +73,6 @@ ARCH_API void ArchAlignedFree(void* ptr); -///@} - } // namespace pxr #endif // PXR_ARCH_ALIGN_H diff --git a/src/pxr/arch/daemon.h b/src/pxr/arch/daemon.h index ab7a5e4..e51eb80 100644 --- a/src/pxr/arch/daemon.h +++ b/src/pxr/arch/daemon.h @@ -9,7 +9,6 @@ #define PXR_ARCH_DAEMON_H /// \file arch/daemon.h -/// \ingroup group_arch_Multithreading /// Create background or daemon processes. #include "./api.h" @@ -42,8 +41,7 @@ namespace pxr { /// \return -1 on error and \c errno will be set to an appropriate /// value. Returns 0 on success. /// -/// \ingroup group_arch_Multithreading -ARCH_API +ARCH_API int ArchCloseAllFiles(int nExcept, const int* exceptFds); } // namespace pxr diff --git a/src/pxr/arch/demangle.h b/src/pxr/arch/demangle.h index ea494f6..d32de8b 100644 --- a/src/pxr/arch/demangle.h +++ b/src/pxr/arch/demangle.h @@ -13,7 +13,6 @@ #endif /// \file arch/demangle.h -/// \ingroup group_arch_Strings /// Demangle C++ typenames generated by the \c typeid() facility. #include "./api.h" @@ -23,9 +22,6 @@ namespace pxr { -/// \addtogroup group_arch_Strings -///@{ - /// Demangle RTTI-generated type name. /// /// Given a variable \c v, the construct \c typeid(v).name() returns @@ -87,8 +83,6 @@ ArchGetDemangled() { return ArchGetDemangled(typeid(T).name()); } -///@} - /// \private ARCH_API void Arch_DemangleFunctionName(std::string* functionName); diff --git a/src/pxr/arch/env.h b/src/pxr/arch/env.h index 101d709..a736f49 100644 --- a/src/pxr/arch/env.h +++ b/src/pxr/arch/env.h @@ -16,53 +16,33 @@ namespace pxr { /// /// Architecture dependent access to environment variables. -/// \ingroup group_arch_SystemFunctions -/// - /// /// Returns \c true if and only if the current environment contains \c name. -/// \ingroup group_arch_SystemFunctions -/// -ARCH_API +ARCH_API bool ArchHasEnv(const std::string &name); -/// /// Gets a value from the current environment identified by \c name. -/// \ingroup group_arch_SystemFunctions -/// -ARCH_API +ARCH_API std::string ArchGetEnv(const std::string &name); -/// /// Creates or modifies an environment variable. -/// \ingroup group_arch_SystemFunctions -/// ARCH_API bool ArchSetEnv(const std::string &name, const std::string &value, bool overwrite); -/// /// Removes an environment variable. -/// \ingroup group_arch_SystemFunctions -/// ARCH_API bool ArchRemoveEnv(const std::string &name); -/// /// Expands environment variables in \c str. -/// \ingroup group_arch_SystemFunctions -/// ARCH_API std::string ArchExpandEnvironmentVariables(const std::string& str); -/// /// Return an array of the environment variables. -/// \ingroup group_arch_SystemFunctions -/// ARCH_API char** ArchEnviron(); diff --git a/src/pxr/arch/errno.h b/src/pxr/arch/errno.h index 88a5afb..794b8c4 100644 --- a/src/pxr/arch/errno.h +++ b/src/pxr/arch/errno.h @@ -9,7 +9,6 @@ #define PXR_ARCH_ERRNO_H /// \file arch/errno.h -/// \ingroup group_arch_SystemFunctions /// Functions for dealing with system errors. #include "./api.h" @@ -17,9 +16,6 @@ namespace pxr { -/// \addtogroup group_arch_SystemFunctions -///@{ - /// Return the error string for the current value of errno. /// /// This function provides a thread-safe method of fetching the error string @@ -40,8 +36,6 @@ ARCH_API std::string ArchStrerror(int errorCode); ARCH_API std::string ArchStrSysError(unsigned long errorCode); #endif -///@} - } // namespace pxr #endif // PXR_ARCH_ERRNO_H diff --git a/src/pxr/arch/error.h b/src/pxr/arch/error.h index f758e44..11df788 100644 --- a/src/pxr/arch/error.h +++ b/src/pxr/arch/error.h @@ -9,7 +9,6 @@ #define PXR_ARCH_ERROR_H /// \file arch/error.h -/// \ingroup group_arch_Diagnostics /// Low-level fatal error reporting. #include "./api.h" @@ -44,9 +43,6 @@ ARCH_API void Arch_Warning(const char* msg, const char* funcName, size_t lineNo, const char* fileName); -/// \addtogroup group_arch_Diagnostics -///@{ - /// Unconditionally aborts the program. /// /// \param msg is a literal string, a \c const \c char* (but not @@ -68,8 +64,6 @@ void Arch_Warning(const char* msg, const char* funcName, #define ARCH_AXIOM(cond) \ if (!(cond)) ARCH_ERROR("[" #cond "] axiom failed") -///@} - } // namespace pxr #endif // PXR_ARCH_ERROR_H diff --git a/src/pxr/arch/export.h b/src/pxr/arch/export.h index 6e657fb..6ea8965 100644 --- a/src/pxr/arch/export.h +++ b/src/pxr/arch/export.h @@ -9,7 +9,6 @@ #define PXR_ARCH_EXPORT_H /// \file arch/export.h -/// \ingroup group_arch_SymbolVisibility /// /// Defines symbol visibility macros. /// diff --git a/src/pxr/arch/fileSystem.h b/src/pxr/arch/fileSystem.h index 0631555..ad072b4 100644 --- a/src/pxr/arch/fileSystem.h +++ b/src/pxr/arch/fileSystem.h @@ -9,7 +9,6 @@ #define PXR_ARCH_FILE_SYSTEM_H /// \file arch/fileSystem.h -/// \ingroup group_arch_SystemFunctions /// Architecture dependent file system access #include "./api.h" @@ -40,8 +39,6 @@ namespace pxr { -/// \addtogroup group_arch_SystemFunctions -///@{ #if !defined(ARCH_OS_WINDOWS) #ifdef _POSIX_VERSION #include /* for PATH_MAX */ @@ -105,7 +102,6 @@ typedef struct stat ArchStatType; /// \file fileSystem.h /// Architecture dependent file system access -/// \ingroup group_arch_SystemFunctions /// /// Opens a file. @@ -406,8 +402,6 @@ inline std::wstring ArchWindowsUtf8ToUtf16(const std::string &str) #endif -///@} - } // namespace pxr #endif // PXR_ARCH_FILE_SYSTEM_H diff --git a/src/pxr/arch/function.h b/src/pxr/arch/function.h index 28ccc04..836a31f 100644 --- a/src/pxr/arch/function.h +++ b/src/pxr/arch/function.h @@ -27,7 +27,6 @@ namespace pxr { /// \c prettyFunction is __ARCH_PRETTY_FUNCTION__, and attempts to /// reconstruct a well formatted function name. /// -/// \ingroup group_arch_Diagnostic ARCH_API std::string ArchGetPrettierFunctionName(const std::string &function, const std::string &prettyFunction); diff --git a/src/pxr/arch/inttypes.h b/src/pxr/arch/inttypes.h index dfe59d4..83b6fe4 100644 --- a/src/pxr/arch/inttypes.h +++ b/src/pxr/arch/inttypes.h @@ -9,7 +9,6 @@ #define PXR_ARCH_INTTYPES_H /// \file arch/inttypes.h -/// \ingroup group_arch_Bits /// Define integral types. /// /// By including this file, the "standard" integer types \c int16_t, diff --git a/src/pxr/arch/library.h b/src/pxr/arch/library.h index 121e72f..6d573e0 100644 --- a/src/pxr/arch/library.h +++ b/src/pxr/arch/library.h @@ -47,10 +47,8 @@ namespace pxr { /// library.h /// Architecture dependent loading and unloading of dynamic libraries. -/// \ingroup group_arch_SystemFunctions /// Load an executable object file. -/// \ingroup group_arch_SystemFunctions /// /// Opens the dynamic library that is specified by filename. /// Returning the handle to the module if successful; false otherwise. @@ -59,18 +57,15 @@ void* ArchLibraryOpen(const std::string &filename, int flag); /// Obtain a description of the most recent error that occurred from /// \c ArchLibraryOpen. -///\ingroup group_arch_SystemFunctions ARCH_API std::string ArchLibraryError(); /// Closes an object opened with \c ArchLibraryOpen. -/// \ingroup group_arch_SystemFunctions ARCH_API int ArchLibraryClose(void* handle); /// Obtain the address of a symbol defined within an object opened with /// \c ArchLibraryOpen. -/// \ingroup group_arch_SystemFunctions /// /// Obtain the address of a symbol that is specified by name. /// Returning the address of the symbol if successful; nullptr otherwise. diff --git a/src/pxr/arch/mallocHook.h b/src/pxr/arch/mallocHook.h index f1c8084..dc0ff4f 100644 --- a/src/pxr/arch/mallocHook.h +++ b/src/pxr/arch/mallocHook.h @@ -9,7 +9,6 @@ #define PXR_ARCH_MALLOC_HOOK_H /// \file arch/mallocHook.h -/// \ingroup group_arch_Memory /// Routines for controlling malloc behavior. #include "./api.h" @@ -26,7 +25,6 @@ namespace pxr { /// special behavior that depends on this library may use this function to /// determine if it is the active allocator. /// -/// \ingroup group_arch_Memory ARCH_API bool ArchIsPtmallocActive(); /// Return true if the C++ STL allocator was requested to be turned off. @@ -35,11 +33,9 @@ ARCH_API bool ArchIsPtmallocActive(); /// GLIBCXX_FORCE_NEW, but it might differ (or not even be possible) for other /// platforms. /// -/// \ingroup group_arch_Memory ARCH_API bool ArchIsStlAllocatorOff(); /// \class ArchMallocHook -/// \ingroup group_arch_Memory /// /// Override default malloc() functionality. /// diff --git a/src/pxr/arch/math.h b/src/pxr/arch/math.h index 71ffb3e..3973dac 100644 --- a/src/pxr/arch/math.h +++ b/src/pxr/arch/math.h @@ -9,7 +9,6 @@ #define PXR_ARCH_MATH_H /// \file arch/math.h -/// \ingroup group_arch_Math /// Architecture-specific math function calls. #include "./defines.h" @@ -26,9 +25,6 @@ namespace pxr { -/// \addtogroup group_arch_Math -///@{ - #if defined (ARCH_CPU_INTEL) || defined (ARCH_CPU_ARM) || defined (doxygen) /// This is the smallest value e such that 1+e^2 == 1, using floats. @@ -134,9 +130,6 @@ ArchCountTrailingZeros(uint64_t x) #endif } - -///@} - } // namespace pxr #endif // PXR_ARCH_MATH_H diff --git a/src/pxr/arch/overview.dox b/src/pxr/arch/overview.dox deleted file mode 100644 index b8eaf9b..0000000 --- a/src/pxr/arch/overview.dox +++ /dev/null @@ -1,94 +0,0 @@ -// This file is used solely to put useful information on the main -// index page produced by doxygen. - -// IF YOU ADD A NEW GROUP, PLEASE ADD IT TO THE LIST BELOW!! - -/// \defgroup group_arch_Bits Bits -/// Functions having to do with how bits are laid out on a machine. - -/// \defgroup group_arch_Multithreading Multithreading -/// Functions having to do with multithreading. - -/// \defgroup group_arch_Math Math -/// Functions for math. - -/// \defgroup group_arch_Strings Strings -/// Functions having to do with string massaging/manipulation - -/// \defgroup group_arch_SystemFunctions System Functions -/// Functions that encapsulate differing low-level system calls. - -/// \defgroup group_arch_Memory Memory Management -/// Functions having to do with memory allocation/handling. - -/// \defgroup group_arch_Diagnostics Diagnostics -/// Functions having to do with error reporting/handling. - -/// \defgroup group_arch_SymbolVisibility Symbol Visibility -/// Macros having to do with symbol visibility - -/*! -\page arch_page_front Arch: Architecture Dependent -\if ( PIXAR_MFB_BUILD ) -\mainpage Arch: Architecture Dependent -\endif - -\section arch_overview Overview - -The ARCH library is a repository for all architecture-dependent -code. It isolates all platform dependencies (and confusing \#ifdefs) -into one small library and also serves as a common area for -documentation of these multi-platform issues. - -The high-level grouping of the classes/functions is: - \li \link group_arch_Bits Bits \endlink - \li \link group_arch_Multithreading Multithreading \endlink - \li \link group_arch_Math Math \endlink - \li \link group_arch_Strings Strings \endlink - \li \link group_arch_SystemFunctions System Functions \endlink - \li \link group_arch_Memory Memory Management \endlink - \li \link group_arch_Diagnostics Diagnostics \endlink - \li \link group_arch_SymbolVisibility Symbol Visibility \endlink - - -Symbols for use within libarch: - -For OS: -
    -
  • ARCH_OS_LINUX -
  • ARCH_OS_DARWIN -
  • ARCH_OS_WINDOWS -
- -For processor: -
    -
  • ARCH_CPU_INTEL -
  • ARCH_CPU_ARM -
- -For bits: -
    -
  • ARCH_BITS_64 -
- -For compiler: -
    -
  • ARCH_COMPILER_CLANG -
      -
    • ARCH_COMPILER_CLANG_MAJOR -
    • ARCH_COMPILER_CLANG_MINOR -
    • ARCH_COMPILER_CLANG_PATCHLEVEL -
    -
  • ARCH_COMPILER_GCC -
      -
    • ARCH_COMPILER_GCC_MAJOR -
    • ARCH_COMPILER_GCC_MINOR -
    • ARCH_COMPILER_GCC_PATCHLEVEL -
    -
  • ARCH_COMPILER_MSVC -
      -
    • ARCH_COMPILER_MSVC_VERSION -
    -
  • ARCH_COMPILER_ICC -
-*/ diff --git a/src/pxr/arch/stackTrace.h b/src/pxr/arch/stackTrace.h index 2bc36cb..acee79d 100644 --- a/src/pxr/arch/stackTrace.h +++ b/src/pxr/arch/stackTrace.h @@ -9,7 +9,6 @@ #define PXR_ARCH_STACK_TRACE_H /// \file arch/stackTrace.h -/// \ingroup group_arch_Diagnostics /// Architecture-specific call-stack tracing routines. #include "./api.h" @@ -25,9 +24,6 @@ namespace pxr { -/// \addtogroup group_arch_Diagnostics -///@{ - /// Dumps call-stack info to a file, prints a message to the terminal, and /// invokes crash handling script. /// @@ -343,8 +339,6 @@ int ArchCrashHandlerSystemv(const char* pathname, char *const argv[], #endif // end ETIME #endif // end ARCH_OS_DARWIN -///@} - } // namespace pxr #endif // PXR_ARCH_STACK_TRACE_H diff --git a/src/pxr/arch/symbols.h b/src/pxr/arch/symbols.h index 2342ba9..10ee7c1 100644 --- a/src/pxr/arch/symbols.h +++ b/src/pxr/arch/symbols.h @@ -9,7 +9,6 @@ #define PXR_ARCH_SYMBOLS_H /// \file arch/symbols.h -/// \ingroup group_arch_Diagnostics /// Architecture-specific symbol lookup routines. #include "./api.h" @@ -29,7 +28,6 @@ namespace pxr { /// the arguments except \p address can be \c NULL if the result isn't needed. /// This will return \c false if \c NULL is passed to \p address. /// -/// \ingroup group_arch_Diagnostics ARCH_API bool ArchGetAddressInfo(void* address, std::string* objectPath, void** baseAddress, diff --git a/src/pxr/arch/systemInfo.h b/src/pxr/arch/systemInfo.h index 91e2ebf..59797c4 100644 --- a/src/pxr/arch/systemInfo.h +++ b/src/pxr/arch/systemInfo.h @@ -9,7 +9,6 @@ #define PXR_ARCH_SYSTEM_INFO_H /// \file arch/systemInfo.h -/// \ingroup group_arch_SystemFunctions /// Provide architecture-specific system information. #include "./api.h" @@ -17,9 +16,6 @@ namespace pxr { -/// \addtogroup group_arch_SystemFunctions -///@{ - /// Return current working directory as a string. ARCH_API std::string ArchGetCwd(); @@ -32,8 +28,6 @@ std::string ArchGetExecutablePath(); ARCH_API int ArchGetPageSize(); -///@} - } // namespace pxr #endif // PXR_ARCH_SYSTEM_INFO_H diff --git a/src/pxr/arch/threads.h b/src/pxr/arch/threads.h index fed4e06..ebd9cfa 100644 --- a/src/pxr/arch/threads.h +++ b/src/pxr/arch/threads.h @@ -9,7 +9,6 @@ #define PXR_ARCH_THREADS_H /// \file arch/threads.h -/// \ingroup group_arch_Multithreading /// Architecture-specific thread function calls. #include "./api.h" @@ -26,7 +25,6 @@ namespace pxr { /// Return true if the calling thread is the main thread, false otherwise. -/// \ingroup group_arch_Multithreading ARCH_API bool ArchIsMainThread(); /// Return the std::thread_id for the thread arch considers to be the "main" diff --git a/src/pxr/arch/timing.h b/src/pxr/arch/timing.h index d945a88..bf92712 100644 --- a/src/pxr/arch/timing.h +++ b/src/pxr/arch/timing.h @@ -9,16 +9,12 @@ #define PXR_ARCH_TIMING_H /// \file arch/timing.h -/// \ingroup group_arch_SystemFunctions /// High-resolution, low-cost timing routines. #include "./api.h" #include "./defines.h" #include "./inttypes.h" -/// \addtogroup group_arch_SystemFunctions -///@{ - #if defined(ARCH_OS_LINUX) && defined(ARCH_CPU_INTEL) #include #elif defined(ARCH_OS_DARWIN) @@ -336,8 +332,6 @@ ArchMeasureExecutionTime( }); } -///@} - } // namespace pxr #endif // PXR_ARCH_TIMING_H diff --git a/src/pxr/arch/virtualMemory.h b/src/pxr/arch/virtualMemory.h index 50bada3..52d6fce 100644 --- a/src/pxr/arch/virtualMemory.h +++ b/src/pxr/arch/virtualMemory.h @@ -9,7 +9,6 @@ #define PXR_ARCH_VIRTUAL_MEMORY_H /// \file arch/virtualMemory.h -/// \ingroup group_arch_SystemFunctions /// Architecture dependent routines for virtual memory. #include "./api.h" diff --git a/src/pxr/arch/vsnprintf.h b/src/pxr/arch/vsnprintf.h index b102c53..640cbc3 100644 --- a/src/pxr/arch/vsnprintf.h +++ b/src/pxr/arch/vsnprintf.h @@ -9,7 +9,6 @@ #define PXR_ARCH_VSNPRINTF_H /// \file arch/vsnprintf.h -/// \ingroup group_arch_Strings /// Architecture dependent memory-safe sprintf capability #include "./api.h" @@ -21,9 +20,6 @@ namespace pxr { -/// \addtogroup group_arch_Strings -///@{ - /// Return the number of characters (not including the null character) /// necessary for a particular sprintf into a string. /// @@ -78,10 +74,8 @@ ARCH_API std::string ArchVStringPrintf(const char *fmt, va_list ap) #ifndef doxygen ARCH_PRINTF_FUNCTION(1, 0) +#endif /* doxygen */ ; -#endif - -/// @} } // namespace pxr