muScalpel

Implemented in TXL and C, muScalpel realizes μTrans and comprises 28k SLoCs, of which 16k is TXL, and 12k is C. muScalpel implements a custom version of GP. Unlike conventional GP, which creates an initial population from individuals that contain multiple statements, muScalpel generates an initial population of individuals with just 1 statement, uniformly selected. muScalpel’s underlying assumption is that our organs need very few of the statements in their donor. Starting from one LOC gives muScalpel the possibility to find small solutions quickly. muScalpel focuses on evolving the organ’s vein. muScalpel also inherits the limitations of TXL, such as its stack limit which precludes parsing large programs and its default C grammar’s inability to properly handle preprocessor directives.

As we all know, software is often difficult to build and run, due to dependencies on its development environment and target platform. muScalpel is no exception. Please keep in mind that we built and ran muScalpel only on 64-bit Ubuntu 14.04 LTS machine, with 16 GB RAM, SSD and 8 physical cores, with its TXL v10.6a-64 (14.7.13), gcc-4.8, cflow (GNU cflow) 1.4 installed. Any other configurations may have affect on the results of the replication of our experiments.

This website contains the source for muScalpel, muScalpel in binary form, and the data sets, including test suites, that underlie our experiments. To facilitate replicating our results, we have written a sequence of scripts that run a *single* run of each of our experiments. The name of the script identifies the experiment. We have worked hard to make each script bullet-proof and have it thoroughly check your environment for its dependencies and tell you what, if anything, is missing. Despite our best efforts, you may still encounter problems. If that happens, please contact us so we can work with you to resolve them.

Experiment Scripts

  • Link to a script that runs all our experiments, as submitted to ISSTA 2015 artifact evaluation track. Here we also provide a dockerized version of our experiments.

  • Links to the scripts used for running each of the experiments.

    For running an experiment untar it and run ./run.sh in the root folder. First we check if you have all the dependencies required for running muScalpel. If you don't have them, you may still chose to run the experiments, but muScalpel may crash, or the results may be affected. After the run finishes, all the results will be in DONOR-HOST/Host_BENEFICIARY. For example:

    tar-xzvf RUN_IDCT-CFLOW.tar.gz && cd IDCT-CFLOW && ./run.sh

    The results will be in: IDCT-CFLOW/Host_BENEFICIARY

Docker Build Files

The following Dockerfiles will run all the experiments in the paper. The first one will use a binary of muScalpel, while the second one builds muScalpel, and then execute the experiments with the compiled version. The Dockerfiles were tested with Docker version 1.0.1, build 990021a. After the run is complete, you will find the results in /home/muScalpelExperiments . Example usage:

sudo docker build -t development/muscalpelexperiments . , in a folder containing Dockerfile . It is recommended that the folders contains only the docker file.

sudo docker run -P -t -i --rm development/muscalpelexperiments /bin/bash will then open a docker container with the results of the experiments in /home/muScalpelExperiments .

  • Dockerfile: Download the Dockerfile that uses a compiled binary of muScalpel.
  • Dockerfile: Download the Dockerfile which also builds muScalpel.

Note: The Dockerfile will fail if your system does not meet the hardware specifications required for running the experiments.

Source Code

The muScalpel prototype requires 64-bit Ubuntu 14.04, TXL, gcc-4.8, cflow and with at least 16 GB memory.

Binary With Example Usage

The muScalpel binary release was compiled on 64-bit Ubuntu 14.04. It contains an example run for the IDCT Donor - Cflow Host transplant, from the empirical study.

Replace /path/to/Cflow-IDCT_Transplant/ with the path to the Cflow-IDCT_Transplant folder. In the attached example this path is: IDCT-CFLOW_BINARY/Cflow-IDCT_Transplant. However, the binary is in IDCT-CFLOW_BINARY, so the path will be just Cflow-IDCT_Transplant.An example run is:



Path=/path/to/Cflow-IDCT_Transplant/ #The path to the folder Cflow-IDCT_Transplant/ in the binary. The end ''/'' is required.
muscalpel #The name of our tool.
--seeds_file ${Path}seed-file #The file which contains the seeds for GI.
--compiler_options ${Path}CFLAGS #Options needed for compiling the code extracted from the donor (additional libraries for example).
--host_target ${Path}Host/cflow-1.4/src/output-file.c #The file in host where the marker __ADDGRAFTHERE__JUSTHERE is contained, the insertion point of the transplant.
--donor_target ${Path}Donor/donor-source.c The file in the donor that contains the core function.
--donor_folder ${Path}Donor/ #The path to the donor source code.
--workspace $Path/ #The workspace of the transplant.
--core_function idct #The core function of the transplant.



The complete command, as it should be pasted is:

./gentrans --seeds_file Cflow-IDCT_Transplant/seed-1.in --compiler_options Cflow-IDCT_Transplant/CFLAGS --host_target Cflow-IDCT_Transplant/Host/cflow-1.4/src/output.c --donor_target Cflow-IDCT_Transplant/Donor/dct.c --donor_folder Cflow-IDCT_Transplant/Donor/ --workspace Cflow-IDCT_Transplant/ --core_function idct --host_project Cflow-IDCT_Transplant/Host

You should run this from IDCT-CFLOW folder. The Organ is automatically grafted into the host program, so, for subsequent runs the original version of the host must be restored. If you wish to run muScalpel on your own transplants, you will need to keep the same folder structure as shown in our examples. The main parameters of muScalpel are:

  • --exclude_functions /path/to/file:(optional parameter) → exclude some functions from the transplantation algorithm. The functions names must be written in a text file: foo bar .

  • --transplant_log /path/to/folder/ :(optional parameter) → log the results of the transplantation operations, in every generation

  • --transplant_statistics /path/to/file:(optional parameter) → log statistics about the transplantation operation

  • --urandom_seeds → muScalpel will take its seeds from /dev/urandom
    --random_seeds → muScalpel will take its seeds from /dev/random. This may take a while.
    --seeds_file /path/to/file → take the seeds from a file. The file must contain 7 lines of 4 numbers each, as in this example.

    The default option is --urandom_seeds.

  • --compiler_options /path/to/file :(optional parameter) → Required if the compilation of the code in donor requires additional options or libraries. The format of this file is: CFLAGS = `libgcrypt-config --libs` . The variable CFLAGS contains all the additional dependencies.

  • --host_target /path/to/file :(required parameter) → the file in the host that contains the __ADDGRAFTHERE__JUSTHERE annotation. This annotation is required, and it marks the place where the organ will be added.

  • --donor_target /path/to/file :(required parameter) → the file in the donor, with the function annotated for transplantation.

  • --txl_tools_path /path/to/folder/ :(optional parameter) → used when the binary files with extension .x are in a different place than muScalpel

    • --donor_folder /path/to/folder/ :(required parameter) → the folder where is the source code of the donor

    --workspace /path/to/folder/ :(required parameter) → the workspace of the transplantation. This is /path/to/Cflow-IDCT_Transplant/ in the above example.

  • --core_function function_name :(required parameter) → the entry point of the functionality to transplant.

2014 © Earl T. Barr, Mark Harman, Yue Jia, Alexandru Marginean, and Justyna Petke

AmazingCounters.com