getting_started.md

Getting Started

System Prerequisites

DAPper is written in Rust and requires the Rust toolchain. It is recommended to use the latest stable Rust version (1.88.0 or newer). You can install through your package manager or through rustup.rs.

Dataset Setup

DAPper uses pre-built datasets that map file names to packages for various ecosystems. These datasets are hosted on Hugging Face and need to be downloaded and placed in the appropriate XDG directory.

Available Datasets

The following datasets are available at https://huggingface.co/dapper-datasets:

• dapper-datasets/pypi - Python Package Index mappings
• dapper-datasets/debian-bookworm - Debian Bookworm packages
• dapper-datasets/debian-bullseye - Debian Bullseye packages
• dapper-datasets/debian-buster - Debian Buster packages
• dapper-datasets/ubuntu-noble - Ubuntu Noble packages
• dapper-datasets/ubuntu-jammy - Ubuntu Jammy packages
• dapper-datasets/ubuntu-focal - Ubuntu Focal packages
• dapper-datasets/NuGet-dataset - .NET NuGet packages

Automated Dataset Set up

Note: If DAPper was installed from source, the following commands can be ran with cargo run -- instead of dapper.

1. List available datasets

   dapper db list-available

2. Install datasets

   • A) Install a dataset

   dapper db install <dataset_name>

   • B) Install all available datasets

   dapper db install all

3. Update datasets

   • A) Update a dataset

   dapper db update <dataset_name>

   • B) Update all datasets

   dapper db update all

4. Uninstall a dataset

   dapper db uninstall <dataset_name>

Manual Dataset Set up

1. Create data directory: Linux:

mkdir -p ${XDG_DATA_HOME:-$HOME/.local/share}/dapper/

macOS:

mkdir -p ${XDG_DATA_HOME:-$HOME/Library/Application Support}/dapper/

Windows (Command Prompt):

mkdir "%LOCALAPPDATA%\dapper\"

2. Download the datasets into the DAPper folder created in step 1.

Installation

For Users:

Cargo Install (Recommended for users):

This installs DAPper without needing to clone the repository.

cargo install dapper@<version>

Afterwards, DAPper can be run using the command dapper. Any examples that show the use of cargo run can be ran using the dapper command instead.

Build from Source (Currently supported):

For ease of use, we recommend using rustup.rs which is a Rust installer and version management tool. Install rustup by following their installation instructions.

1. Clone the DAPper git repository using git

git clone https://github.com/LLNL/dapper.git
cd dapper

2. Build DAPper

cargo build --release

3. Run DAPper

# Using cargo
cargo run <source code directory or file>

Precompiled Binaries (Coming soon):

We plan to provide precompiled binaries on the GitHub releases page for easier installation across different platforms.

Installation Verification

To verify your installation works correctly:

1. Create a simple test C++ file OR use a test file from the repository dapper/tests/test_files:

   // test.cpp
   #include <iostream>
   #include <vector>
   
   int main() {
       std::cout << "Hello World" << std::endl;
       return 0;
   }

2. Run DAPper on the test file:

   cargo run test.cpp

   or if cargo install dapper was used instead of building from source:

   dapper test.cpp

3. You should see output showing possible implicit dependencies within the source code. In the example, the output will be the #included files vector and iostream from test.cpp.

For Developers:

1. Clone with development branch (if available):

   git clone https://github.com/LLNL/dapper.git
   cd dapper

2. Install development formatting and linting tools:

   # Install rustfmt for code formatting
   rustup component add rustfmt
   
   # Install clippy for linting
   rustup component add clippy

3. Build in debug mode:

   cargo build

4. Run tests:

   cargo test

5. Run DAPper

# Using cargo
cargo run <source code directory or file>

Development Workflow

• Format code: cargo fmt
• Lint code: cargo clippy
• Run in debug mode: cargo run <arguments>