From fb5d4c3871029c633c0249645b014203bcc785d2 Mon Sep 17 00:00:00 2001 From: wuxx1279 Date: Mon, 8 Dec 2025 23:37:37 -0600 Subject: [PATCH 01/12] update readme --- README.md | 42 ++++++++++++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index ca20d70b1..bd6e3ef84 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,41 @@ # Testsuite for the Dyninst tool for binary instrumentation, analysis, and modification -## Usage +## Building Testsuite -Because Dyninst and its testsuite are tightly integrated, it is highly recommended to use the build script located in `scripts/build/build.pl`. +To build testsuite, please first have the Dyninst version you want to test installed. +Then one can build the testsuite using cmake by specifying the path of dyninst installation using Dyninst\_ROOT. -Example usage on Linux: + > mkdir build + > cd build; + > cmake .. -DDyninst\_ROOT=/path/to/your/dyninst/installation -DCMAKE\_INSTALL\_PREFIX=/path/to/your/testsuite/intallation - > export PERL5LIB=testsuite/scripts/build - > perl testsuite/scripts/build/build.pl --njobs=4 - -The build script has several options for configuring library locations. See `build.pl --help` for details. +## Running Testsuite -### Running tests for pull requests +To run the testsuite, three paths need to be set through the enviromental variable: +DYNINSTAPI\_RT\_LIB should point to the libdyninstAPI\_RT.so under the Dyninst installation path. +LD\_LIBRARY\_PATH should include both the path of tht Dyninst installation and the path of the testsuite installation. -By default, the build script uses the current state of the repositories contained in the directories specified by `--dyninst-src` and `--test-src`. The test script comes with the ability to fetch and update pull requests directly from the Dyninst Github repository. These are controlled through the `--dyninst-pr` and `--testsuite-pr` switches for dyninst and the testsuite, respectively. Note, however, that if the current git tree has any outstanding changes, the script will raise an error accordingly. +To enable debugging, one can run the testsuite with the following arguments -The format of the input is *remote/id* where *remote* is the name given to the remote repository (this is usually "origin") and *id* is the pull request id from Github. In the case that the remote's name is 'origin', it can be omitted. Hence, `--dyninst-pr=origin/123` is the same as `--dyninst-pr=123`; the same for `--testsuite-pr`. +> -v -log logfilename -debugPrint -The build script will also update the pull request (via a squashed merge commit) to the current HEAD of the remote's `master` branch the first time the PR is tested locally. As such, this feature should only be used to test PRs against the official Dyninst repository. This process creates a local branch name `PR` where `` is the *id* of the PR specified on the command line. If this local branch already exists, then a `pull` is issued and no merge commit against the remote's master is performed. This can cause trouble if a local branch with that name already exists. +The testsuite can be run two modes: The full run mode and a one-test mode. - NOTE: It is best not to have any local branches with names of the form 'PR' when using the build script +### runTests + +The runTests executable will run all tests the comes with the testsuite. + +Example usage : +> DYNINSTAPI\_RT\_LIB=dyninst-install/lib/libdyninstAPI\_RT.so LD\_LIBRARY\_PATH=dyninst-install/lib/:./:$LD\_LIBRARY\_PATH ./runTests -v -log output.log -debugPrint + +### test\_driver + +The test\_driver allows you to specify which test you want to run by passing hte following argument + +> -test test-name + +Example usage : +> DYNINSTAPI\_RT\_LIB=dyninst-install/lib/libdyninstAPI\_RT.so LD\_LIBRARY\_PATH=dyninst-install/lib/:./:$LD\_LIBRARY\_PATH ./test\_driver -v -log output.log -debugPrint -test pc\_irpc + +### Documentation for additional control(WIP) From a6075438ddbdbeb0ed0f5b09089db99d1faad732 Mon Sep 17 00:00:00 2001 From: bbiiggppiigg Date: Tue, 9 Dec 2025 14:41:22 +0900 Subject: [PATCH 02/12] Update README.md From f5d81e3693edf76c23f188f5345d5f760e0a6422 Mon Sep 17 00:00:00 2001 From: bbiiggppiigg Date: Tue, 9 Dec 2025 14:48:16 +0900 Subject: [PATCH 03/12] Update README.md --- README.md | 42 +++++++++++++++++++++++++++++------------- 1 file changed, 29 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index bd6e3ef84..503941b03 100644 --- a/README.md +++ b/README.md @@ -5,37 +5,53 @@ To build testsuite, please first have the Dyninst version you want to test installed. Then one can build the testsuite using cmake by specifying the path of dyninst installation using Dyninst\_ROOT. - > mkdir build - > cd build; - > cmake .. -DDyninst\_ROOT=/path/to/your/dyninst/installation -DCMAKE\_INSTALL\_PREFIX=/path/to/your/testsuite/intallation +``` +mkdir build + +cd build + +cmake .. -DDyninst_ROOT=/path/to/your/dyninst/installation -DCMAKE_INSTALL_PREFIX=/path/to/your/testsuite/intallation +``` ## Running Testsuite To run the testsuite, three paths need to be set through the enviromental variable: -DYNINSTAPI\_RT\_LIB should point to the libdyninstAPI\_RT.so under the Dyninst installation path. -LD\_LIBRARY\_PATH should include both the path of tht Dyninst installation and the path of the testsuite installation. + +* DYNINSTAPI\_RT\_LIB should point to the libdyninstAPI\_RT.so under the Dyninst installation path. + +* LD\_LIBRARY\_PATH should include both the path of tht Dyninst installation and the path of the testsuite installation. To enable debugging, one can run the testsuite with the following arguments -> -v -log logfilename -debugPrint +``` +-v -log logfilename -debugPrint +``` The testsuite can be run two modes: The full run mode and a one-test mode. -### runTests +## runTests The runTests executable will run all tests the comes with the testsuite. -Example usage : -> DYNINSTAPI\_RT\_LIB=dyninst-install/lib/libdyninstAPI\_RT.so LD\_LIBRARY\_PATH=dyninst-install/lib/:./:$LD\_LIBRARY\_PATH ./runTests -v -log output.log -debugPrint +Example usage: + +``` +DYNINSTAPI_RT_LIB=dyninst-install/lib/libdyninstAPI_RT.so LD_LIBRARY_PATH=dyninst-install/lib/:./:$LD_LIBRARY_PATH ./runTests -v -log output.log -debugPrint +``` -### test\_driver +## test\_driver The test\_driver allows you to specify which test you want to run by passing hte following argument -> -test test-name +` +-test test-name +` + +Example usage: -Example usage : -> DYNINSTAPI\_RT\_LIB=dyninst-install/lib/libdyninstAPI\_RT.so LD\_LIBRARY\_PATH=dyninst-install/lib/:./:$LD\_LIBRARY\_PATH ./test\_driver -v -log output.log -debugPrint -test pc\_irpc +``` +DYNINSTAPI_RT_LIB=dyninst-install/lib/libdyninstAPI_RT.so LD_LIBRARY_PATH=dyninst-install/lib/:./:$LD_LIBRARY_PATH ./test_driver -v -log output.log -debugPrint -test pc_irpc +``` ### Documentation for additional control(WIP) From ee884dfb5986d073c9fd09bf541b43e81d15a6a7 Mon Sep 17 00:00:00 2001 From: bbiiggppiigg Date: Thu, 11 Dec 2025 11:51:32 +0800 Subject: [PATCH 04/12] Update README.md Co-authored-by: Tim Haines --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 503941b03..f903fea13 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ ## Building Testsuite To build testsuite, please first have the Dyninst version you want to test installed. -Then one can build the testsuite using cmake by specifying the path of dyninst installation using Dyninst\_ROOT. +Then one can build the testsuite using cmake by specifying the path of dyninst installation using `Dyninst_ROOT`. ``` mkdir build From f875ce805fe0ddb4d7caea743c97e1c2f2e25e2c Mon Sep 17 00:00:00 2001 From: bbiiggppiigg Date: Thu, 11 Dec 2025 11:52:08 +0800 Subject: [PATCH 05/12] Update README.md Co-authored-by: Tim Haines --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f903fea13..c50841e9a 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ To run the testsuite, three paths need to be set through the enviromental variab * DYNINSTAPI\_RT\_LIB should point to the libdyninstAPI\_RT.so under the Dyninst installation path. -* LD\_LIBRARY\_PATH should include both the path of tht Dyninst installation and the path of the testsuite installation. +* `LD_LIBRARY_PATH` should include both the path of tht Dyninst installation and the path of the testsuite installation. To enable debugging, one can run the testsuite with the following arguments From 55f22c3cb68a9fea6b61a4066966b3d67fb92282 Mon Sep 17 00:00:00 2001 From: bbiiggppiigg Date: Thu, 11 Dec 2025 11:52:23 +0800 Subject: [PATCH 06/12] Update README.md Co-authored-by: Tim Haines --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c50841e9a..9dc3588a6 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ DYNINSTAPI_RT_LIB=dyninst-install/lib/libdyninstAPI_RT.so LD_LIBRARY_PATH=dynins ## test\_driver -The test\_driver allows you to specify which test you want to run by passing hte following argument +The test\_driver allows you to specify which test you want to run by passing the following argument ` -test test-name From ab6291f950bc3c68efea3b471f0922688494f139 Mon Sep 17 00:00:00 2001 From: bbiiggppiigg Date: Thu, 11 Dec 2025 11:55:41 +0800 Subject: [PATCH 07/12] Update README.md Co-authored-by: Tim Haines --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 9dc3588a6..b041744dc 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,9 @@ The runTests executable will run all tests the comes with the testsuite. Example usage: ``` -DYNINSTAPI_RT_LIB=dyninst-install/lib/libdyninstAPI_RT.so LD_LIBRARY_PATH=dyninst-install/lib/:./:$LD_LIBRARY_PATH ./runTests -v -log output.log -debugPrint +export DYNINSTAPI_RT_LIB=dyninst-install/lib/libdyninstAPI_RT.so +export LD_LIBRARY_PATH=dyninst-install/lib/:./:$LD_LIBRARY_PATH +./runTests -v -log output.log -debugPrint -all ``` ## test\_driver From 5b55df1b507efd73e882fd5c3dab131c6f3394de Mon Sep 17 00:00:00 2001 From: bbiiggppiigg Date: Thu, 11 Dec 2025 11:57:28 +0800 Subject: [PATCH 08/12] Update README.md --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b041744dc..8950acf66 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ cmake .. -DDyninst_ROOT=/path/to/your/dyninst/installation -DCMAKE_INSTALL_PREFI To run the testsuite, three paths need to be set through the enviromental variable: -* DYNINSTAPI\_RT\_LIB should point to the libdyninstAPI\_RT.so under the Dyninst installation path. +* `DYNINSTAPI_RT_LIB` should point to the `libdyninstAPI_RT.so` under the Dyninst installation path. * `LD_LIBRARY_PATH` should include both the path of tht Dyninst installation and the path of the testsuite installation. @@ -52,7 +52,9 @@ The test\_driver allows you to specify which test you want to run by passing the Example usage: ``` -DYNINSTAPI_RT_LIB=dyninst-install/lib/libdyninstAPI_RT.so LD_LIBRARY_PATH=dyninst-install/lib/:./:$LD_LIBRARY_PATH ./test_driver -v -log output.log -debugPrint -test pc_irpc +export DYNINSTAPI_RT_LIB=dyninst-install/lib/libdyninstAPI_RT.so +export LD_LIBRARY_PATH=dyninst-install/lib/:./:$LD_LIBRARY_PATH +./test_driver -v -log output.log -debugPrint -test pc_irpc ``` ### Documentation for additional control(WIP) From f6bb10bf4c586451296f7c5358b59206ed47b931 Mon Sep 17 00:00:00 2001 From: bbiiggppiigg Date: Thu, 11 Dec 2025 11:59:07 +0800 Subject: [PATCH 09/12] Update README.md --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8950acf66..30bf80d1d 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,8 @@ # Testsuite for the Dyninst tool for binary instrumentation, analysis, and modification -## Building Testsuite +## Building and Installing Testsuite +The testsuite needs to be installed as it cannot be run from within the build directory. To build testsuite, please first have the Dyninst version you want to test installed. Then one can build the testsuite using cmake by specifying the path of dyninst installation using `Dyninst_ROOT`. @@ -36,6 +37,7 @@ The runTests executable will run all tests the comes with the testsuite. Example usage: ``` +cd /path/to/your/testsuite/intallation export DYNINSTAPI_RT_LIB=dyninst-install/lib/libdyninstAPI_RT.so export LD_LIBRARY_PATH=dyninst-install/lib/:./:$LD_LIBRARY_PATH ./runTests -v -log output.log -debugPrint -all @@ -52,6 +54,7 @@ The test\_driver allows you to specify which test you want to run by passing the Example usage: ``` +cd /path/to/your/testsuite/intallation export DYNINSTAPI_RT_LIB=dyninst-install/lib/libdyninstAPI_RT.so export LD_LIBRARY_PATH=dyninst-install/lib/:./:$LD_LIBRARY_PATH ./test_driver -v -log output.log -debugPrint -test pc_irpc From f4fe5e92000405c8744a246faa7e45f12464bdd4 Mon Sep 17 00:00:00 2001 From: bbiiggppiigg Date: Thu, 11 Dec 2025 11:59:31 +0800 Subject: [PATCH 10/12] Update README.md --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 30bf80d1d..222dce2a0 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,9 @@ ## Building and Installing Testsuite The testsuite needs to be installed as it cannot be run from within the build directory. + To build testsuite, please first have the Dyninst version you want to test installed. + Then one can build the testsuite using cmake by specifying the path of dyninst installation using `Dyninst_ROOT`. ``` From ec12c1e0e5acab9305eb08517a55aec788decc52 Mon Sep 17 00:00:00 2001 From: bbiiggppiigg Date: Thu, 11 Dec 2025 12:01:22 +0800 Subject: [PATCH 11/12] Update README.md --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 222dce2a0..28931fa6b 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ The testsuite needs to be installed as it cannot be run from within the build directory. -To build testsuite, please first have the Dyninst version you want to test installed. +To build the testsuite, please first have the Dyninst version you want to test installed. Then one can build the testsuite using cmake by specifying the path of dyninst installation using `Dyninst_ROOT`. @@ -30,11 +30,11 @@ To enable debugging, one can run the testsuite with the following arguments -v -log logfilename -debugPrint ``` -The testsuite can be run two modes: The full run mode and a one-test mode. +The testsuite can be run two modes: To run all tests or to run a specific test. ## runTests -The runTests executable will run all tests the comes with the testsuite. +The runTests executable will run all the tests that comes with the testsuite. Example usage: @@ -47,7 +47,7 @@ export LD_LIBRARY_PATH=dyninst-install/lib/:./:$LD_LIBRARY_PATH ## test\_driver -The test\_driver allows you to specify which test you want to run by passing the following argument +The test\_driver executable allows you run a specific test by passing the following argument ` -test test-name From 6b00b4b76fa8c457f671940b5621e11990587856 Mon Sep 17 00:00:00 2001 From: bbiiggppiigg Date: Sat, 13 Dec 2025 00:50:41 +0800 Subject: [PATCH 12/12] Update README.md --- README.md | 45 +++++++++++++++++++++++++++++++-------------- 1 file changed, 31 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 28931fa6b..16cad0b5f 100644 --- a/README.md +++ b/README.md @@ -8,12 +8,33 @@ To build the testsuite, please first have the Dyninst version you want to test i Then one can build the testsuite using cmake by specifying the path of dyninst installation using `Dyninst_ROOT`. -``` -mkdir build +### define variable used here and in the rest of this README + +```shell +DYNINST_INSTALL=/path/to/your/Dyninst/installation +TESTSUITE_DIR=/path/to/the/testsuite +TESTSUITE_BUILD=$TESTSUITE_DIR/build +TESTSUITE_INSTALL=$TESTSUITE_DIR/install + +mkdir $TESTSUITE_BUILD +cd $TESTSUITE_BUILD + +# configure +cmake -DDyninst_ROOT=$DYNINST_INSTALL -DCMAKE_INSTALL_PREFIX=$TESTSUITE_INSTALL .. -cd build +# build and install +make -j install -cmake .. -DDyninst_ROOT=/path/to/your/dyninst/installation -DCMAKE_INSTALL_PREFIX=/path/to/your/testsuite/intallation +# find the Dyninst lib directory (varies by platform, so use glob) +DYNINST_INSTALL_LIB=$(echo $DYNINST_INSTALL/lib*) +if [ ! -d "$DYNINST_INSTALL_LIB" ]; then + # check that lib directory exists; detect no or more than 1 glob match + echo "ERROR: Dyninst install lib directory not found: $DYNINST_INSTALL_LIB" 1>&2 +fi + +# define more variables needed to run the test suite +export DYNINSTAPI_RT_LIB=$DYNINST_INSTALL_LIB/libdyninstAPI_RT.so +TESTSUITE_LD_LIBRARY_PATH=$DYNINST_INSTALL_LIB:$TESTSUITE_INSTALL:$LD_LIBRARY_PATH ``` ## Running Testsuite @@ -38,11 +59,9 @@ The runTests executable will run all the tests that comes with the testsuite. Example usage: -``` -cd /path/to/your/testsuite/intallation -export DYNINSTAPI_RT_LIB=dyninst-install/lib/libdyninstAPI_RT.so -export LD_LIBRARY_PATH=dyninst-install/lib/:./:$LD_LIBRARY_PATH -./runTests -v -log output.log -debugPrint -all +```shell +cd $TESTSUITE_INSTALL +LD_LIBRARY_PATH=$TESTSUITE_LD_LIBRARY_PATH ./runTests -v -log output.log -debugPrint -all ``` ## test\_driver @@ -55,11 +74,9 @@ The test\_driver executable allows you run a specific test by passing the follow Example usage: -``` -cd /path/to/your/testsuite/intallation -export DYNINSTAPI_RT_LIB=dyninst-install/lib/libdyninstAPI_RT.so -export LD_LIBRARY_PATH=dyninst-install/lib/:./:$LD_LIBRARY_PATH -./test_driver -v -log output.log -debugPrint -test pc_irpc +```shell +cd $TESTSUITE_INSTALL +LD_LIBRARY_PATH=$TESTSUITE_LD_LIBRARY_PATH ./test_driver -v -log output.log -debugPrint -test pc_irpc ``` ### Documentation for additional control(WIP)