all.sh: add some documentation

This commit is contained in:
Gilles Peskine 2017-12-21 15:59:21 +01:00
parent 273ac90383
commit e8be5e2571

View file

@ -4,20 +4,77 @@
#
# This file is part of mbed TLS (https://tls.mbed.org)
#
# Copyright (c) 2014-2016, ARM Limited, All Rights Reserved
#
# Copyright (c) 2014-2017, ARM Limited, All Rights Reserved
################################################################
#### Documentation
################################################################
# Purpose
# -------
#
# To run all tests possible or available on the platform.
#
# Notes for users
# ---------------
#
# Warning: the test is destructive. It includes various build modes and
# configurations, and can and will arbitrarily change the current CMake
# configuration. After this script has been run, the CMake cache will be lost
# and CMake will no longer be initialised.
# configuration. The following files must be committed into git:
# * include/polarssl/config.h
# * Makefile, library/Makefile, programs/Makefile, tests/Makefile
# After running this script, the CMake cache will be lost and CMake
# will no longer be initialised.
#
# The script assumes the presence of gcc and clang (recent enough for using
# ASan with gcc and MemSan with clang, or valgrind) are available, as well as
# cmake and a "good" find.
# The script assumes the presence of a number of tools:
# * Basic Unix tools (Windows users note: a Unix-style find must be before
# the Windows find in the PATH)
# * Perl
# * GNU Make
# * CMake
# * GCC and Clang (recent enough for using ASan with gcc and MemSan with clang, or valgrind)
# * arm-gcc and mingw-gcc
# * ArmCC 5 and ArmCC 6, unless invoked with --no-armcc
# * OpenSSL and GnuTLS command line tools, recent enough for the
# interoperability tests. If they don't support SSLv3 then a legacy
# version of these tools must be present as well (search for LEGACY
# below).
# See the invocation of check_tools below for details.
#
# This script must be invoked from the toplevel directory of a git
# working copy of Mbed TLS.
#
# Note that the output is not saved. You may want to run
# script -c tests/scripts/all.sh
# or
# tests/scripts/all.sh >all.log 2>&1
#
# Notes for maintainers
# ---------------------
#
# The tests are roughly in order from fastest to slowest. This doesn't
# have to be exact, but in general you should add slower tests towards
# the end and fast checks near the beginning.
#
# Sanity checks have the following form:
# 1. msg "short description of what is about to be done"
# 2. run sanity check (failure stops the script)
#
# Build or build-and-test steps have the following form:
# 1. msg "short description of what is about to be done"
# 2. cleanup
# 3. preparation (config.pl, cmake, ...) (failure stops the script)
# 4. make
# 5. Run tests if relevant. All tests must be prefixed with
# if_build_successful for the sake of --keep-going.
################################################################
#### Initialization and command line parsing
################################################################
# Abort on errors (and uninitialised variables)
set -eu
@ -310,6 +367,12 @@ if [ $RUN_ARMCC -ne 0 ]; then
check_tools "armcc"
fi
################################################################
#### Basic checks
################################################################
#
# Test Suites to be executed
#
@ -327,6 +390,12 @@ scripts/recursion.pl library/*.c
msg "test: freshness of generated source files" # < 1s
tests/scripts/check-generated-files.sh
################################################################
#### Build and test many configurations and targets
################################################################
msg "build: cmake, gcc, ASan" # ~ 1 min 50s
cleanup
CC=gcc cmake -D CMAKE_BUILD_TYPE:String=Asan .
@ -578,6 +647,12 @@ make test
cd "$MBEDTLS_ROOT_DIR"
rm -rf "$OUT_OF_SOURCE_DIR"
################################################################
#### Termination
################################################################
msg "Done, cleaning up"
cleanup