[thirdparty/openssl.git] / NOTES-Valgrind.md


NOTES FOR VALGRIND
==================

Valgrind is a test harness that includes many tools such as memcheck,
which is commonly used to check for memory leaks, etc. The default tool
run by Valgrind is memcheck. There are other tools available, but this
will focus on memcheck.

Valgrind runs programs in a virtual machine, this means OpenSSL unit
tests run under Valgrind will take longer than normal.

Requirements
------------

1. Platform supported by Valgrind
   See: http://valgrind.org/info/platforms.html
2. Valgrind installed on the platform
   See: http://valgrind.org/downloads/current.html
3. OpensSSL compiled
   See: [INSTALL.md](INSTALL.md)

Running Tests
-------------

Test behavior can be modified by adjusting environment variables.

`EXE_SHELL`

This variable is used to specify the shell used to execute OpenSSL test
programs. The default wrapper (util/wrap.pl) initializes the environment
to allow programs to find shared libraries. The variable can be modified
to specify a different executable environment.

    EXE_SHELL="`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 --leak-check=full -q"

This will start up Valgrind with the default checker (memcheck).
The --error-exitcode=1 option specifies that Valgrind should exit with an
error code of 1 when memory leaks occur.
The --leak-check=full option specifies extensive memory checking.
The -q option prints only error messages.
Additional Valgrind options may be added to the EXE_SHELL variable.

`OPENSSL_ia32cap`

This variable controls the processor-specific code on Intel processors.
By default, OpenSSL will attempt to figure out the capabilities of a
processor, and use it to its fullest capability. This variable can be
used to control what capabilities OpenSSL uses.

As of valgrind-3.15.0 on Linux/x86_64, instructions up to AVX2 are
supported. Setting the following disables instructions beyond AVX2:

`OPENSSL_ia32cap=":0"`

This variable may need to be set to something different based on the
processor and Valgrind version you are running tests on. More information
may be found in [docs/man3/OPENSSL_ia32cap.pod](docs/man3/OPENSSL_ia32cap.pod).

Additional variables (such as `VERBOSE` and `TESTS`) are described in the
file [test/README.md](test/README.md).

Example command line:

    $ make test EXE_SHELL="`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 --leak-check=full -q" OPENSSL_ia32cap=":0"

If an error occurs, you can then run the specific test via the `TESTS`
variable with the VERBOSE option to gather additional information.

    $ make test VERBOSE=1 TESTS=test_test EXE_SHELL="`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 --leak-check=full -q" OPENSSL_ia32cap=":0"
Commit	Line	Data
e616c11e TS	1
	2	NOTES FOR VALGRIND
	3	==================
	4
	5	Valgrind is a test harness that includes many tools such as memcheck,
	6	which is commonly used to check for memory leaks, etc. The default tool
	7	run by Valgrind is memcheck. There are other tools available, but this
	8	will focus on memcheck.
	9
	10	Valgrind runs programs in a virtual machine, this means OpenSSL unit
	11	tests run under Valgrind will take longer than normal.
	12
	13	Requirements
	14	------------
	15
	16	1. Platform supported by Valgrind
	17	See: http://valgrind.org/info/platforms.html
	18	2. Valgrind installed on the platform
	19	See: http://valgrind.org/downloads/current.html
	20	3. OpensSSL compiled
3a0b3cc9	21	See: [INSTALL.md](INSTALL.md)
e616c11e TS	22
	23	Running Tests
	24	-------------
	25
	26	Test behavior can be modified by adjusting environment variables.
	27
3a0b3cc9	28	`EXE_SHELL`
e616c11e TS	29
e616c11e TS	30	This variable is used to specify the shell used to execute OpenSSL test
30a4cda5 RL	31	programs. The default wrapper (util/wrap.pl) initializes the environment
	32	to allow programs to find shared libraries. The variable can be modified
	33	to specify a different executable environment.
e616c11e	34
3a0b3cc9	35	EXE_SHELL="`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 --leak-check=full -q"
e616c11e TS	36
	37	This will start up Valgrind with the default checker (memcheck).
	38	The --error-exitcode=1 option specifies that Valgrind should exit with an
	39	error code of 1 when memory leaks occur.
	40	The --leak-check=full option specifies extensive memory checking.
	41	The -q option prints only error messages.
	42	Additional Valgrind options may be added to the EXE_SHELL variable.
	43
3a0b3cc9	44	`OPENSSL_ia32cap`
e616c11e TS	45
	46	This variable controls the processor-specific code on Intel processors.
	47	By default, OpenSSL will attempt to figure out the capabilities of a
	48	processor, and use it to its fullest capability. This variable can be
	49	used to control what capabilities OpenSSL uses.
	50
	51	As of valgrind-3.15.0 on Linux/x86_64, instructions up to AVX2 are
	52	supported. Setting the following disables instructions beyond AVX2:
	53
9afbb681	54	`OPENSSL_ia32cap=":0"`
e616c11e TS	55
	56	This variable may need to be set to something different based on the
	57	processor and Valgrind version you are running tests on. More information
3a0b3cc9	58	may be found in [docs/man3/OPENSSL_ia32cap.pod](docs/man3/OPENSSL_ia32cap.pod).
e616c11e	59
3a0b3cc9	60	Additional variables (such as `VERBOSE` and `TESTS`) are described in the
9afbb681	61	file [test/README.md](test/README.md).
e616c11e TS	62
	63	Example command line:
	64
9afbb681	65	$ make test EXE_SHELL="`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 --leak-check=full -q" OPENSSL_ia32cap=":0"
e616c11e	66
3a0b3cc9	67	If an error occurs, you can then run the specific test via the `TESTS`
e616c11e TS	68	variable with the VERBOSE option to gather additional information.
e616c11e TS	69
9afbb681	70	$ make test VERBOSE=1 TESTS=test_test EXE_SHELL="`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 --leak-check=full -q" OPENSSL_ia32cap=":0"