From ba68290cb3086abfdffa9d0f829d2331ff3b7749 Mon Sep 17 00:00:00 2001 From: Gennadiy Civil Date: Wed, 19 Jun 2019 16:20:19 -0400 Subject: small docs restucture and cleanup --- CONTRIBUTING.md | 4 +- googlemock/docs/Documentation.md | 2 +- googletest/docs/Pkgconfig.md | 146 ---------------------------------- googletest/docs/pkgconfig.md | 146 ++++++++++++++++++++++++++++++++++ googletest/scripts/release_docs.py | 158 ------------------------------------- 5 files changed, 149 insertions(+), 307 deletions(-) delete mode 100644 googletest/docs/Pkgconfig.md create mode 100644 googletest/docs/pkgconfig.md delete mode 100755 googletest/scripts/release_docs.py diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c273fdc..dcaa070 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -80,7 +80,7 @@ itself is a valuable contribution. To keep the source consistent, readable, diffable and easy to merge, we use a fairly rigid coding style, as defined by the [google-styleguide](https://github.com/google/styleguide) project. All patches will be expected -to conform to the style outlined [here](https://google.github.io/styleguide/cppguide.html). +to conform to the style outlined [here](https://google.github.io/styleguide/cppguide.html). Use [.clang-format](https://github.com/google/googletest/blob/master/.clang-format) to check your formatting ## Requirements for Contributors ### @@ -136,7 +136,7 @@ gtest-type-util.h in the same directory. You don't need to worry about regenerating the source files unless you need to modify them. You would then modify the corresponding `.pump` files and run the '[pump.py](googletest/scripts/pump.py)' -generator script. See the [Pump Manual](googletest/docs/PumpManual.md). +generator script. See the [Pump Manual](googletest/docs/pump_manual.md). ## Developing Google Mock ### diff --git a/googlemock/docs/Documentation.md b/googlemock/docs/Documentation.md index a42bd11..f621259 100644 --- a/googlemock/docs/Documentation.md +++ b/googlemock/docs/Documentation.md @@ -12,4 +12,4 @@ the respective git branch/tag).** To contribute code to Google Mock, read: * [CONTRIBUTING](../../CONTRIBUTING.md) -- read this _before_ writing your first patch. - * [Pump Manual](../../googletest/docs/PumpManual.md) -- how we generate some of Google Mock's source files. + * [Pump Manual](../../googletest/docs/pump_manual.md) -- how we generate some of the source files. diff --git a/googletest/docs/Pkgconfig.md b/googletest/docs/Pkgconfig.md deleted file mode 100644 index 5ad1f01..0000000 --- a/googletest/docs/Pkgconfig.md +++ /dev/null @@ -1,146 +0,0 @@ -## Using GoogleTest from various build systems ## - -GoogleTest comes with pkg-config files that can be used to determine all -necessary flags for compiling and linking to GoogleTest (and GoogleMock). -Pkg-config is a standardised plain-text format containing - - * the includedir (-I) path - * necessary macro (-D) definitions - * further required flags (-pthread) - * the library (-L) path - * the library (-l) to link to - -All current build systems support pkg-config in one way or another. For -all examples here we assume you want to compile the sample -`samples/sample3_unittest.cc`. - - -### CMake ### - -Using `pkg-config` in CMake is fairly easy: - -``` cmake -cmake_minimum_required(VERSION 3.0) - -cmake_policy(SET CMP0048 NEW) -project(my_gtest_pkgconfig VERSION 0.0.1 LANGUAGES CXX) - -find_package(PkgConfig) -pkg_search_module(GTEST REQUIRED gtest_main) - -add_executable(testapp samples/sample3_unittest.cc) -target_link_libraries(testapp ${GTEST_LDFLAGS}) -target_compile_options(testapp PUBLIC ${GTEST_CFLAGS}) - -include(CTest) -add_test(first_and_only_test testapp) -``` - -It is generally recommended that you use `target_compile_options` + `_CFLAGS` -over `target_include_directories` + `_INCLUDE_DIRS` as the former includes not -just -I flags (GoogleTest might require a macro indicating to internal headers -that all libraries have been compiled with threading enabled. In addition, -GoogleTest might also require `-pthread` in the compiling step, and as such -splitting the pkg-config `Cflags` variable into include dirs and macros for -`target_compile_definitions()` might still miss this). The same recommendation -goes for using `_LDFLAGS` over the more commonplace `_LIBRARIES`, which -happens to discard `-L` flags and `-pthread`. - - -### Autotools ### - -Finding GoogleTest in Autoconf and using it from Automake is also fairly easy: - -In your `configure.ac`: - -``` -AC_PREREQ([2.69]) -AC_INIT([my_gtest_pkgconfig], [0.0.1]) -AC_CONFIG_SRCDIR([samples/sample3_unittest.cc]) -AC_PROG_CXX - -PKG_CHECK_MODULES([GTEST], [gtest_main]) - -AM_INIT_AUTOMAKE([foreign subdir-objects]) -AC_CONFIG_FILES([Makefile]) -AC_OUTPUT -``` - -and in your `Makefile.am`: - -``` -check_PROGRAMS = testapp -TESTS = $(check_PROGRAMS) - -testapp_SOURCES = samples/sample3_unittest.cc -testapp_CXXFLAGS = $(GTEST_CFLAGS) -testapp_LDADD = $(GTEST_LIBS) -``` - - -### Meson ### - -Meson natively uses pkgconfig to query dependencies: - -``` -project('my_gtest_pkgconfig', 'cpp', version : '0.0.1') - -gtest_dep = dependency('gtest_main') - -testapp = executable( - 'testapp', - files(['samples/sample3_unittest.cc']), - dependencies : gtest_dep, - install : false) - -test('first_and_only_test', testapp) -``` - - -### Plain Makefiles ### - -Since `pkg-config` is a small Unix command-line utility, it can be used -in handwritten `Makefile`s too: - -``` Makefile -GTEST_CFLAGS = `pkg-config --cflags gtest_main` -GTEST_LIBS = `pkg-config --libs gtest_main` - -.PHONY: tests all - -tests: all - ./testapp - -all: testapp - -testapp: testapp.o - $(CXX) $(CXXFLAGS) $(LDFLAGS) $< -o $@ $(GTEST_LIBS) - -testapp.o: samples/sample3_unittest.cc - $(CXX) $(CPPFLAGS) $(CXXFLAGS) $< -c -o $@ $(GTEST_CFLAGS) -``` - - -### Help! pkg-config can't find GoogleTest! ### - -Let's say you have a `CMakeLists.txt` along the lines of the one in this -tutorial and you try to run `cmake`. It is very possible that you get a -failure along the lines of: - -``` --- Checking for one of the modules 'gtest_main' -CMake Error at /usr/share/cmake/Modules/FindPkgConfig.cmake:640 (message): - None of the required 'gtest_main' found -``` - -These failures are common if you installed GoogleTest yourself and have not -sourced it from a distro or other package manager. If so, you need to tell -pkg-config where it can find the `.pc` files containing the information. -Say you installed GoogleTest to `/usr/local`, then it might be that the -`.pc` files are installed under `/usr/local/lib64/pkgconfig`. If you set - -``` -export PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig -``` - -pkg-config will also try to look in `PKG_CONFIG_PATH` to find `gtest_main.pc`. diff --git a/googletest/docs/pkgconfig.md b/googletest/docs/pkgconfig.md new file mode 100644 index 0000000..5ad1f01 --- /dev/null +++ b/googletest/docs/pkgconfig.md @@ -0,0 +1,146 @@ +## Using GoogleTest from various build systems ## + +GoogleTest comes with pkg-config files that can be used to determine all +necessary flags for compiling and linking to GoogleTest (and GoogleMock). +Pkg-config is a standardised plain-text format containing + + * the includedir (-I) path + * necessary macro (-D) definitions + * further required flags (-pthread) + * the library (-L) path + * the library (-l) to link to + +All current build systems support pkg-config in one way or another. For +all examples here we assume you want to compile the sample +`samples/sample3_unittest.cc`. + + +### CMake ### + +Using `pkg-config` in CMake is fairly easy: + +``` cmake +cmake_minimum_required(VERSION 3.0) + +cmake_policy(SET CMP0048 NEW) +project(my_gtest_pkgconfig VERSION 0.0.1 LANGUAGES CXX) + +find_package(PkgConfig) +pkg_search_module(GTEST REQUIRED gtest_main) + +add_executable(testapp samples/sample3_unittest.cc) +target_link_libraries(testapp ${GTEST_LDFLAGS}) +target_compile_options(testapp PUBLIC ${GTEST_CFLAGS}) + +include(CTest) +add_test(first_and_only_test testapp) +``` + +It is generally recommended that you use `target_compile_options` + `_CFLAGS` +over `target_include_directories` + `_INCLUDE_DIRS` as the former includes not +just -I flags (GoogleTest might require a macro indicating to internal headers +that all libraries have been compiled with threading enabled. In addition, +GoogleTest might also require `-pthread` in the compiling step, and as such +splitting the pkg-config `Cflags` variable into include dirs and macros for +`target_compile_definitions()` might still miss this). The same recommendation +goes for using `_LDFLAGS` over the more commonplace `_LIBRARIES`, which +happens to discard `-L` flags and `-pthread`. + + +### Autotools ### + +Finding GoogleTest in Autoconf and using it from Automake is also fairly easy: + +In your `configure.ac`: + +``` +AC_PREREQ([2.69]) +AC_INIT([my_gtest_pkgconfig], [0.0.1]) +AC_CONFIG_SRCDIR([samples/sample3_unittest.cc]) +AC_PROG_CXX + +PKG_CHECK_MODULES([GTEST], [gtest_main]) + +AM_INIT_AUTOMAKE([foreign subdir-objects]) +AC_CONFIG_FILES([Makefile]) +AC_OUTPUT +``` + +and in your `Makefile.am`: + +``` +check_PROGRAMS = testapp +TESTS = $(check_PROGRAMS) + +testapp_SOURCES = samples/sample3_unittest.cc +testapp_CXXFLAGS = $(GTEST_CFLAGS) +testapp_LDADD = $(GTEST_LIBS) +``` + + +### Meson ### + +Meson natively uses pkgconfig to query dependencies: + +``` +project('my_gtest_pkgconfig', 'cpp', version : '0.0.1') + +gtest_dep = dependency('gtest_main') + +testapp = executable( + 'testapp', + files(['samples/sample3_unittest.cc']), + dependencies : gtest_dep, + install : false) + +test('first_and_only_test', testapp) +``` + + +### Plain Makefiles ### + +Since `pkg-config` is a small Unix command-line utility, it can be used +in handwritten `Makefile`s too: + +``` Makefile +GTEST_CFLAGS = `pkg-config --cflags gtest_main` +GTEST_LIBS = `pkg-config --libs gtest_main` + +.PHONY: tests all + +tests: all + ./testapp + +all: testapp + +testapp: testapp.o + $(CXX) $(CXXFLAGS) $(LDFLAGS) $< -o $@ $(GTEST_LIBS) + +testapp.o: samples/sample3_unittest.cc + $(CXX) $(CPPFLAGS) $(CXXFLAGS) $< -c -o $@ $(GTEST_CFLAGS) +``` + + +### Help! pkg-config can't find GoogleTest! ### + +Let's say you have a `CMakeLists.txt` along the lines of the one in this +tutorial and you try to run `cmake`. It is very possible that you get a +failure along the lines of: + +``` +-- Checking for one of the modules 'gtest_main' +CMake Error at /usr/share/cmake/Modules/FindPkgConfig.cmake:640 (message): + None of the required 'gtest_main' found +``` + +These failures are common if you installed GoogleTest yourself and have not +sourced it from a distro or other package manager. If so, you need to tell +pkg-config where it can find the `.pc` files containing the information. +Say you installed GoogleTest to `/usr/local`, then it might be that the +`.pc` files are installed under `/usr/local/lib64/pkgconfig`. If you set + +``` +export PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig +``` + +pkg-config will also try to look in `PKG_CONFIG_PATH` to find `gtest_main.pc`. diff --git a/googletest/scripts/release_docs.py b/googletest/scripts/release_docs.py deleted file mode 100755 index 1291347..0000000 --- a/googletest/scripts/release_docs.py +++ /dev/null @@ -1,158 +0,0 @@ -#!/usr/bin/env python -# -# Copyright 2013 Google Inc. 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. -# * Neither the name of Google Inc. 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 COPYRIGHT HOLDERS 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 COPYRIGHT -# OWNER 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. - -"""Script for branching Google Test/Mock wiki pages for a new version. - -SYNOPSIS - release_docs.py NEW_RELEASE_VERSION - - Google Test and Google Mock's external user documentation is in - interlinked wiki files. When we release a new version of - Google Test or Google Mock, we need to branch the wiki files - such that users of a specific version of Google Test/Mock can - look up documenation relevant for that version. This script - automates that process by: - - - branching the current wiki pages (which document the - behavior of the SVN trunk head) to pages for the specified - version (e.g. branching FAQ.wiki to V2_6_FAQ.wiki when - NEW_RELEASE_VERSION is 2.6); - - updating the links in the branched files to point to the branched - version (e.g. a link in V2_6_FAQ.wiki that pointed to - Primer.wiki#Anchor will now point to V2_6_Primer.wiki#Anchor). - - NOTE: NEW_RELEASE_VERSION must be a NEW version number for - which the wiki pages don't yet exist; otherwise you'll get SVN - errors like "svn: Path 'V1_7_PumpManual.wiki' is not a - directory" when running the script. - -EXAMPLE - $ cd PATH/TO/GTEST_SVN_WORKSPACE/trunk - $ scripts/release_docs.py 2.6 # create wiki pages for v2.6 - $ svn status # verify the file list - $ svn diff # verify the file contents - $ svn commit -m "release wiki pages for v2.6" -""" - -__author__ = 'wan@google.com (Zhanyong Wan)' - -import os -import re -import sys - -import common - - -# Wiki pages that shouldn't be branched for every gtest/gmock release. -GTEST_UNVERSIONED_WIKIS = ['DevGuide.wiki'] -GMOCK_UNVERSIONED_WIKIS = [ - 'DesignDoc.wiki', - 'DevGuide.wiki', - 'KnownIssues.wiki' - ] - - -def DropWikiSuffix(wiki_filename): - """Removes the .wiki suffix (if any) from the given filename.""" - - return (wiki_filename[:-len('.wiki')] if wiki_filename.endswith('.wiki') - else wiki_filename) - - -class WikiBrancher(object): - """Branches ...""" - - def __init__(self, dot_version): - self.project, svn_root_path = common.GetSvnInfo() - if self.project not in ('googletest', 'googlemock'): - sys.exit('This script must be run in a gtest or gmock SVN workspace.') - self.wiki_dir = svn_root_path + '/wiki' - # Turn '2.6' to 'V2_6_'. - self.version_prefix = 'V' + dot_version.replace('.', '_') + '_' - self.files_to_branch = self.GetFilesToBranch() - page_names = [DropWikiSuffix(f) for f in self.files_to_branch] - # A link to Foo.wiki is in one of the following forms: - # [Foo words] - # [Foo#Anchor words] - # [http://code.google.com/.../wiki/Foo words] - # [http://code.google.com/.../wiki/Foo#Anchor words] - # We want to replace 'Foo' with 'V2_6_Foo' in the above cases. - self.search_for_re = re.compile( - # This regex matches either - # [Foo - # or - # /wiki/Foo - # followed by a space or a #, where Foo is the name of an - # unversioned wiki page. - r'(\[|/wiki/)(%s)([ #])' % '|'.join(page_names)) - self.replace_with = r'\1%s\2\3' % (self.version_prefix,) - - def GetFilesToBranch(self): - """Returns a list of .wiki file names that need to be branched.""" - - unversioned_wikis = (GTEST_UNVERSIONED_WIKIS if self.project == 'googletest' - else GMOCK_UNVERSIONED_WIKIS) - return [f for f in os.listdir(self.wiki_dir) - if (f.endswith('.wiki') and - not re.match(r'^V\d', f) and # Excluded versioned .wiki files. - f not in unversioned_wikis)] - - def BranchFiles(self): - """Branches the .wiki files needed to be branched.""" - - print 'Branching %d .wiki files:' % (len(self.files_to_branch),) - os.chdir(self.wiki_dir) - for f in self.files_to_branch: - command = 'svn cp %s %s%s' % (f, self.version_prefix, f) - print command - os.system(command) - - def UpdateLinksInBranchedFiles(self): - - for f in self.files_to_branch: - source_file = os.path.join(self.wiki_dir, f) - versioned_file = os.path.join(self.wiki_dir, self.version_prefix + f) - print 'Updating links in %s.' % (versioned_file,) - text = file(source_file, 'r').read() - new_text = self.search_for_re.sub(self.replace_with, text) - file(versioned_file, 'w').write(new_text) - - -def main(): - if len(sys.argv) != 2: - sys.exit(__doc__) - - brancher = WikiBrancher(sys.argv[1]) - brancher.BranchFiles() - brancher.UpdateLinksInBranchedFiles() - - -if __name__ == '__main__': - main() -- cgit v0.12