From 37376b2ecb903ae69e55c962ce6cda2ea5f4fcf8 Mon Sep 17 00:00:00 2001 From: Murphy Tian Date: Sun, 15 Jun 2025 18:34:26 +0800 Subject: [PATCH 1/7] [test] npm release with GitHub Actions --- .github/workflows/npm-release.yml | 142 ++++++++++++++++++++++++++++++ libCacheSim-node/package.json | 24 ++--- 2 files changed, 154 insertions(+), 12 deletions(-) create mode 100644 .github/workflows/npm-release.yml diff --git a/.github/workflows/npm-release.yml b/.github/workflows/npm-release.yml new file mode 100644 index 00000000..ad8596bc --- /dev/null +++ b/.github/workflows/npm-release.yml @@ -0,0 +1,142 @@ +name: NPM Release + +on: + release: + types: [published] + workflow_dispatch: + inputs: + version: + description: 'Version to publish' + required: true + default: '1.0.0' + +env: + BUILD_TYPE: Release + +jobs: + build-and-publish: + strategy: + matrix: + include: + - os: ubuntu-latest + target: linux-x64 + - os: macos-latest + target: darwin-x64 + - os: macos-13 + target: darwin-arm64 + + runs-on: ${{ matrix.os }} + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + registry-url: 'https://registry.npmjs.org' + + - name: Install system dependencies (Ubuntu) + if: matrix.os == 'ubuntu-latest' + run: | + sudo apt-get update + sudo apt-get install -y build-essential cmake libglib2.0-dev libzstd-dev + + - name: Install system dependencies (macOS) + if: startsWith(matrix.os, 'macos') + run: | + brew install cmake glib zstd + + - name: Set target architecture (macOS ARM64) + if: matrix.target == 'darwin-arm64' + run: | + echo "CMAKE_OSX_ARCHITECTURES=arm64" >> $GITHUB_ENV + echo "ARCHFLAGS=-arch arm64" >> $GITHUB_ENV + echo "npm_config_target_arch=arm64" >> $GITHUB_ENV + + - name: Build libCacheSim + run: | + mkdir -p _build + cd _build + if [ "${{ matrix.target }}" = "darwin-arm64" ]; then + cmake -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} -DCMAKE_OSX_ARCHITECTURES=arm64 .. + else + cmake -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} .. + fi + make -j$(nproc 2>/dev/null || sysctl -n hw.ncpu) + + - name: Install Node.js dependencies + working-directory: libCacheSim-node + run: npm install + + - name: Build and upload prebuilt binary + working-directory: libCacheSim-node + run: | + if [ "${{ matrix.target }}" = "darwin-arm64" ]; then + CFLAGS=-fPIC CXXFLAGS=-fPIC npx prebuild --target-arch arm64 --upload-all + else + CFLAGS=-fPIC CXXFLAGS=-fPIC npx prebuild --upload-all + fi + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Test binary + working-directory: libCacheSim-node + run: node -e "console.log('Testing binary load...'); require('./index.js');" + + publish-npm: + needs: build-and-publish + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + registry-url: 'https://registry.npmjs.org' + + - name: Prepare package for publishing + working-directory: libCacheSim-node + run: | + # Update version if provided via workflow dispatch + if [ "${{ github.event.inputs.version }}" != "" ]; then + npm version ${{ github.event.inputs.version }} --no-git-tag-version + fi + + # Install production dependencies only + npm ci --only=production + + - name: Publish to NPM + working-directory: libCacheSim-node + run: npm publish --access public + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + + - name: Create GitHub Release (if workflow_dispatch) + if: github.event_name == 'workflow_dispatch' + uses: actions/create-release@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tag_name: v${{ github.event.inputs.version }} + release_name: Release v${{ github.event.inputs.version }} + body: | + Release v${{ github.event.inputs.version }} + + ## Installation + ```bash + npm install libcachesim-node + ``` + + ## Supported Platforms + - Linux x64 + - macOS x64 (Intel) + - macOS arm64 (Apple Silicon) + + Pre-compiled binaries are automatically downloaded during installation. + draft: false + prerelease: false \ No newline at end of file diff --git a/libCacheSim-node/package.json b/libCacheSim-node/package.json index b0c52727..722d343e 100644 --- a/libCacheSim-node/package.json +++ b/libCacheSim-node/package.json @@ -1,18 +1,14 @@ { - "name": "libcachesim-node", - "version": "1.0.0", + "name": "@realtmxi/libcachesim-node", + "version": "1.0.0-beta.1", "main": "index.js", "bin": { "cachesim-js": "./cli.js" }, "scripts": { - "prebuild": "npm run ensure-libcachesim", - "ensure-libcachesim": "cd .. && rm -rf _build && mkdir _build && cd _build && cmake -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DCMAKE_BUILD_TYPE=${DEBUG:+Debug}${DEBUG:-Release} .. && make -j", - "install": "npm run build", - "build": "CFLAGS=-fPIC CXXFLAGS=-fPIC node-gyp rebuild", - "clean": "node-gyp clean && cd .. && rm -rf _build", "test": "node test.js", - "prepack": "npm run build" + "install": "prebuild-install", + "prebuild": "prebuild --all --strip --verbose" }, "keywords": [ "cache", @@ -29,9 +25,9 @@ "description": "Node.js bindings for libCacheSim - A high-performance cache simulator and analysis library supporting LRU, FIFO, S3-FIFO, Sieve and other caching algorithms", "repository": { "type": "git", - "url": "https://github.com/1a1a11a/libCacheSim" + "url": "https://github.com/realtmxi/libCacheSim" }, - "homepage": "https://github.com/1a1a11a/libCacheSim/tree/develop/libCacheSim-node", + "homepage": "https://github.com/realtmxi/libCacheSim/tree/npm-release/libCacheSim-node", "bugs": { "url": "https://github.com/1a1a11a/libCacheSim/issues" }, @@ -39,9 +35,13 @@ "node": ">=14.0.0" }, "dependencies": { - "node-addon-api": "^8.3.1" + "node-addon-api": "^8.3.1", + "prebuild-install": "^7.1.2" + }, + "devDependencies": { + "node-gyp": "^10.0.0", + "prebuild": "^13.0.1" }, - "devDependencies": {}, "files": [ "index.js", "cli.js", From f656665fd5433e589bc553a5319bdb7d36f29938 Mon Sep 17 00:00:00 2001 From: Murphy Tian Date: Mon, 16 Jun 2025 15:50:01 +0800 Subject: [PATCH 2/7] fix: solve merge confliction --- .github/workflows/npm-release.yml | 176 +++++++++++++++++------------- libCacheSim-node/binding.gyp | 22 ++-- libCacheSim-node/package.json | 15 ++- 3 files changed, 122 insertions(+), 91 deletions(-) diff --git a/.github/workflows/npm-release.yml b/.github/workflows/npm-release.yml index ad8596bc..8e9c1620 100644 --- a/.github/workflows/npm-release.yml +++ b/.github/workflows/npm-release.yml @@ -9,27 +9,79 @@ on: description: 'Version to publish' required: true default: '1.0.0' + push: + branches: + - npm-release env: BUILD_TYPE: Release jobs: - build-and-publish: - strategy: - matrix: - include: - - os: ubuntu-latest - target: linux-x64 - - os: macos-latest - target: darwin-x64 - - os: macos-13 - target: darwin-arm64 + create-release: + runs-on: ubuntu-latest + outputs: + release_created: ${{ steps.release.outputs.release_created }} + version: ${{ steps.package.outputs.version }} - runs-on: ${{ matrix.os }} + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Get package version + id: package + working-directory: libCacheSim-node + run: | + VERSION=$(node -p "require('./package.json').version") + echo "version=$VERSION" >> $GITHUB_OUTPUT + echo "Version: $VERSION" + + - name: Check if release exists + id: check_release + run: | + VERSION="${{ steps.package.outputs.version }}" + if gh release view "v$VERSION" > /dev/null 2>&1; then + echo "Release v$VERSION already exists" + echo "exists=true" >> $GITHUB_OUTPUT + else + echo "Release v$VERSION does not exist" + echo "exists=false" >> $GITHUB_OUTPUT + fi + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Create GitHub Release + id: release + if: steps.check_release.outputs.exists == 'false' + uses: actions/create-release@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tag_name: v${{ steps.package.outputs.version }} + release_name: Release v${{ steps.package.outputs.version }} + body: | + Release v${{ steps.package.outputs.version }} + + ## Installation + ```bash + npm install @realtmxi/libcachesim-node + ``` + + ## Supported Platforms + - Linux x64 + + Pre-compiled binaries are automatically downloaded during installation. + draft: false + prerelease: true + + build-and-publish: + needs: create-release + runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 + with: + fetch-depth: 0 - name: Setup Node.js uses: actions/setup-node@v4 @@ -37,34 +89,25 @@ jobs: node-version: '18' registry-url: 'https://registry.npmjs.org' - - name: Install system dependencies (Ubuntu) - if: matrix.os == 'ubuntu-latest' + - name: Install system dependencies run: | sudo apt-get update sudo apt-get install -y build-essential cmake libglib2.0-dev libzstd-dev - - name: Install system dependencies (macOS) - if: startsWith(matrix.os, 'macos') - run: | - brew install cmake glib zstd - - - name: Set target architecture (macOS ARM64) - if: matrix.target == 'darwin-arm64' - run: | - echo "CMAKE_OSX_ARCHITECTURES=arm64" >> $GITHUB_ENV - echo "ARCHFLAGS=-arch arm64" >> $GITHUB_ENV - echo "npm_config_target_arch=arm64" >> $GITHUB_ENV - - name: Build libCacheSim run: | + echo "Building libCacheSim for Linux x64..." mkdir -p _build cd _build - if [ "${{ matrix.target }}" = "darwin-arm64" ]; then - cmake -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} -DCMAKE_OSX_ARCHITECTURES=arm64 .. - else - cmake -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} .. - fi - make -j$(nproc 2>/dev/null || sysctl -n hw.ncpu) + cmake -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} .. -DCMAKE_VERBOSE_MAKEFILE=ON + echo "Starting build..." + make -j$(nproc) VERBOSE=1 + + - name: Prepare vendored library + run: | + mkdir -p libCacheSim-node/vendor/include + cp _build/liblibCacheSim.a libCacheSim-node/vendor/ + cp -r libCacheSim/include/* libCacheSim-node/vendor/include/ - name: Install Node.js dependencies working-directory: libCacheSim-node @@ -73,17 +116,22 @@ jobs: - name: Build and upload prebuilt binary working-directory: libCacheSim-node run: | - if [ "${{ matrix.target }}" = "darwin-arm64" ]; then - CFLAGS=-fPIC CXXFLAGS=-fPIC npx prebuild --target-arch arm64 --upload-all - else - CFLAGS=-fPIC CXXFLAGS=-fPIC npx prebuild --upload-all - fi + echo "Building Node.js addon for Linux x64..." + echo "Node.js version: $(node --version)" + echo "NPM version: $(npm --version)" + ls -la ../ + ls -la ../_build/ + CFLAGS=-fPIC CXXFLAGS=-fPIC npx prebuild --upload-all --verbose env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Test binary working-directory: libCacheSim-node - run: node -e "console.log('Testing binary load...'); require('./index.js');" + run: | + echo "Testing binary load for Linux x64..." + ls -la + ls -la prebuilds/ || echo "No prebuilds directory found" + node -e "console.log('Testing binary load...'); try { require('./index.js'); console.log('Binary loaded successfully!'); } catch(e) { console.error('Failed to load binary:', e); process.exit(1); }" publish-npm: needs: build-and-publish @@ -98,45 +146,27 @@ jobs: with: node-version: '18' registry-url: 'https://registry.npmjs.org' - - - name: Prepare package for publishing - working-directory: libCacheSim-node - run: | - # Update version if provided via workflow dispatch - if [ "${{ github.event.inputs.version }}" != "" ]; then - npm version ${{ github.event.inputs.version }} --no-git-tag-version - fi - # Install production dependencies only - npm ci --only=production + - name: Install system dependencies + run: | + sudo apt-get update + sudo apt-get install -y build-essential cmake libglib2.0-dev libzstd-dev + + - name: Build libCacheSim + run: | + mkdir -p _build + cd _build + cmake -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} .. + make -j$(nproc) + + - name: Prepare vendored library + run: | + mkdir -p libCacheSim-node/vendor/include + cp _build/liblibCacheSim.a libCacheSim-node/vendor/ + cp -r libCacheSim/include/* libCacheSim-node/vendor/include/ - name: Publish to NPM working-directory: libCacheSim-node run: npm publish --access public env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} - - - name: Create GitHub Release (if workflow_dispatch) - if: github.event_name == 'workflow_dispatch' - uses: actions/create-release@v1 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - tag_name: v${{ github.event.inputs.version }} - release_name: Release v${{ github.event.inputs.version }} - body: | - Release v${{ github.event.inputs.version }} - - ## Installation - ```bash - npm install libcachesim-node - ``` - - ## Supported Platforms - - Linux x64 - - macOS x64 (Intel) - - macOS arm64 (Apple Silicon) - - Pre-compiled binaries are automatically downloaded during installation. - draft: false - prerelease: false \ No newline at end of file + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} \ No newline at end of file diff --git a/libCacheSim-node/binding.gyp b/libCacheSim-node/binding.gyp index c89f1dd7..a1bf61e7 100644 --- a/libCacheSim-node/binding.gyp +++ b/libCacheSim-node/binding.gyp @@ -5,15 +5,11 @@ "sources": [ "binding.cc" ], "include_dirs": [ " Date: Mon, 16 Jun 2025 15:51:18 +0800 Subject: [PATCH 3/7] Merge from npm-release to murphy/npm-release-0616 (#1) --- libCacheSim-node/README.md | 201 ++++++++++++++++++++++++++++++++++ libCacheSim-node/package.json | 2 +- libCacheSim-node/test.cc | 28 +++++ package-lock.json | 6 + 4 files changed, 236 insertions(+), 1 deletion(-) create mode 100644 libCacheSim-node/README.md create mode 100644 libCacheSim-node/test.cc create mode 100644 package-lock.json diff --git a/libCacheSim-node/README.md b/libCacheSim-node/README.md new file mode 100644 index 00000000..14d30704 --- /dev/null +++ b/libCacheSim-node/README.md @@ -0,0 +1,201 @@ +# libCacheSim Node.js Bindings + +Node.js bindings for libCacheSim - A high-performance cache simulator and analysis library supporting LRU, FIFO, S3-FIFO, Sieve and other caching algorithms. + +## Features + +- **High Performance**: Built on the optimized libCacheSim C library +- **Multiple Algorithms**: Support for LRU, FIFO, LFU, ARC, Clock, S3-FIFO, Sieve, and more +- **Various Trace Types**: Support for vscsi, csv, txt, binary, and oracle trace formats +- **Pre-compiled Binaries**: Fast installation with no build tools required +- **Cross-platform**: Support for Linux (x64) and macOS (x64, ARM64) + +## Installation + +```bash +npm install libcachesim-node +``` + +The package includes pre-compiled binaries for supported platforms. No additional build tools or dependencies are required for end users. + +### Supported Platforms + +- **Linux**: x64 (Ubuntu 18.04+, other distributions with compatible glibc) +- **macOS**: x64 (Intel) and ARM64 (Apple Silicon) + +If pre-compiled binaries are not available for your platform, please check the releases page for updates or submit an issue. + +## Quick Start + +```javascript +const { runSimulation, getSupportedAlgorithms } = require('libcachesim-node'); + +// Get supported algorithms +console.log('Supported algorithms:', getSupportedAlgorithms()); + +// Run a cache simulation +const result = runSimulation( + '/path/to/trace.vscsi', // Path to trace file + 'vscsi', // Trace type + 's3fifo', // Cache algorithm + '1mb' // Cache size +); + +console.log('Simulation results:', result); +``` + +## API Reference + +### `runSimulation(tracePath, traceType, algorithm, cacheSize)` + +Run a cache simulation with specified parameters. + +**Parameters:** +- `tracePath` (string): Path to the trace file +- `traceType` (string): Type of trace file ('vscsi', 'csv', 'txt', 'binary', 'oracle') +- `algorithm` (string): Cache replacement algorithm +- `cacheSize` (string): Cache size (e.g., '1mb', '512kb', '2gb') + +**Returns:** Object containing simulation results including hit rate, miss count, etc. + +### `getSupportedAlgorithms()` + +Get a list of supported cache algorithms. + +**Returns:** Array of algorithm names + +### `getSupportedTraceTypes()` + +Get a list of supported trace file types. + +**Returns:** Array of trace type names + +## Cache Algorithms + +The following cache replacement algorithms are supported: + +- **LRU** (Least Recently Used) +- **FIFO** (First In, First Out) +- **LFU** (Least Frequently Used) +- **ARC** (Adaptive Replacement Cache) +- **Clock** (Clock/Second Chance) +- **S3-FIFO** (Simple, Scalable, Scan-resistant FIFO) +- **Sieve** (Eviction algorithm with lazy promotion) + +## Trace File Formats + +- **vscsi**: VMware vSCSI trace format +- **csv**: Comma-separated values format +- **txt**: Plain text format +- **binary**: Binary trace format +- **oracle**: Oracle optimal algorithm simulation + +## Command Line Interface + +The package includes a command-line interface: + +```bash +# Install globally for CLI access +npm install -g libcachesim-node + +# Run simulation from command line +cachesim-js --trace /path/to/trace.vscsi --algorithm s3fifo --size 1mb +``` + +## Development + +### Building from Source + +If you need to build from source or contribute to development: + +```bash +# Clone the repository +git clone https://github.com/1a1a11a/libCacheSim.git +cd libCacheSim/libCacheSim-node + +# Install dependencies +npm install + +# Build from source (requires cmake, build tools) +npm run build-from-source + +# Run tests +npm test +``` + +### Requirements for Building from Source + +- Node.js 14+ +- CMake 3.10+ +- C/C++ compiler (GCC, Clang, or MSVC) +- System dependencies: + - Linux: `build-essential cmake libglib2.0-dev libzstd-dev` + - macOS: `cmake glib zstd` (via Homebrew) + +## Architecture + +This package uses `prebuild-install` for binary distribution: + +1. **Pre-compiled Binaries**: Automatically downloaded from GitHub releases during installation +2. **Automated Building**: GitHub Actions automatically builds binaries for all supported platforms +3. **Standard Tooling**: Uses industry-standard `prebuild` and `prebuild-install` packages + +## Troubleshooting + +### Installation Issues + +If installation fails, try the following: + +```bash +# Clear npm cache +npm cache clean --force + +# Reinstall with verbose logging +npm install libcachesim-node --verbose + +# Force source compilation +npm install libcachesim-node --build-from-source +``` + +### Binary Loading Issues + +If you see binary loading errors: + +1. Ensure your platform is supported +2. Check that the `prebuilds` directory exists and contains your platform's binary +3. Try reinstalling the package +4. Check Node.js version compatibility (requires Node.js 14+) + +### Build from Source Issues + +If source compilation fails: + +1. Install required system dependencies +2. Ensure CMake 3.10+ is available +3. Check that libCacheSim builds successfully: `cd .. && mkdir _build && cd _build && cmake .. && make` + +## Contributing + +Contributions are welcome! Please see the main [libCacheSim repository](https://github.com/1a1a11a/libCacheSim) for contribution guidelines. + +## License + +MIT License - see the LICENSE file for details. + +## Related Projects + +- [libCacheSim](https://github.com/1a1a11a/libCacheSim) - The core C library +- [libCacheSim Python bindings](https://github.com/1a1a11a/libCacheSim/tree/develop/libCacheSim/pyBindings) - Python interface + +## Citation + +If you use libCacheSim in your research, please cite: + +```bibtex +@misc{libcachesim, + title={libCacheSim: A High-Performance Cache Simulator}, + author={Tian, Murphy and others}, + year={2023}, + url={https://github.com/1a1a11a/libCacheSim} +} +``` \ No newline at end of file diff --git a/libCacheSim-node/package.json b/libCacheSim-node/package.json index 02634610..2b760079 100644 --- a/libCacheSim-node/package.json +++ b/libCacheSim-node/package.json @@ -59,4 +59,4 @@ "publishConfig": { "registry": "https://registry.npmjs.org/" } -} \ No newline at end of file +} diff --git a/libCacheSim-node/test.cc b/libCacheSim-node/test.cc new file mode 100644 index 00000000..5b3eb97b --- /dev/null +++ b/libCacheSim-node/test.cc @@ -0,0 +1,28 @@ +// test.cc +#include +#include "../libCacheSim/include/libCacheSim.h" + + +int main() { + std::cout << "Trying to include libCacheSim..." << std::endl; + + // Set up basic cache parameters + common_cache_params_t params = { + .cache_size = 1024 * 1024, // 1 MB cache + .default_ttl = 0, + .hashpower = 24 + }; + + // Try to create an LRU cache + cache_t* cache = LRU_init(params, nullptr); + + if (cache) { + std::cout << "Successfully created an LRU cache." << std::endl; + cache->cache_free(cache); // Proper cleanup + } else { + std::cerr << "Failed to create cache." << std::endl; + return 1; + } + + return 0; +} diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 00000000..9aa73453 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,6 @@ +{ + "name": "libCacheSim", + "lockfileVersion": 3, + "requires": true, + "packages": {} +} From cdc68da396f56f3fab2e4edb2c6de3c45d0d59b8 Mon Sep 17 00:00:00 2001 From: Murphy Tian Date: Mon, 16 Jun 2025 16:01:28 +0800 Subject: [PATCH 4/7] [refactoring] modify test part code, delete unnecessary files --- .github/workflows/npm-release.yml | 16 +-- libCacheSim-node/libCacheSim-node.md | 198 --------------------------- libCacheSim-node/package.json | 10 +- libCacheSim-node/test.cc | 28 ---- 4 files changed, 11 insertions(+), 241 deletions(-) delete mode 100644 libCacheSim-node/libCacheSim-node.md delete mode 100644 libCacheSim-node/test.cc diff --git a/.github/workflows/npm-release.yml b/.github/workflows/npm-release.yml index 8e9c1620..4cba7bb3 100644 --- a/.github/workflows/npm-release.yml +++ b/.github/workflows/npm-release.yml @@ -3,15 +3,11 @@ name: NPM Release on: release: types: [published] - workflow_dispatch: - inputs: - version: - description: 'Version to publish' - required: true - default: '1.0.0' push: branches: - - npm-release + - main + paths: + - 'libCacheSim-node/**' env: BUILD_TYPE: Release @@ -63,7 +59,7 @@ jobs: ## Installation ```bash - npm install @realtmxi/libcachesim-node + npm install libcachesim-node ``` ## Supported Platforms @@ -71,7 +67,7 @@ jobs: Pre-compiled binaries are automatically downloaded during installation. draft: false - prerelease: true + prerelease: false build-and-publish: needs: create-release @@ -164,7 +160,7 @@ jobs: mkdir -p libCacheSim-node/vendor/include cp _build/liblibCacheSim.a libCacheSim-node/vendor/ cp -r libCacheSim/include/* libCacheSim-node/vendor/include/ - + - name: Publish to NPM working-directory: libCacheSim-node run: npm publish --access public diff --git a/libCacheSim-node/libCacheSim-node.md b/libCacheSim-node/libCacheSim-node.md deleted file mode 100644 index 27a33fc1..00000000 --- a/libCacheSim-node/libCacheSim-node.md +++ /dev/null @@ -1,198 +0,0 @@ -# libcachesim-node - -Node.js bindings for libCacheSim. - - -## Installation - -### Local Installation (Development) - -```bash -cd libCacheSim-node -npm install -g node-gyp -npm install -npm run build -``` - -### Global Installation - -To install libcachesim-node globally and make the CLI available system-wide: - -```bash -cd libCacheSim-node -npm install -g . -``` - -After global installation, you can use the CLI from any directory: - -```bash -cachesim-js --help -cachesim-js --trace /path/to/trace.vscsi --type vscsi --algorithm lru --size 10mb -``` - -**Note:** Global installation requires the libCacheSim C++ library to be built first. Make sure you have: -- CMake installed -- A C++ compiler (gcc/clang) -- The parent libCacheSim repository properly built - -If you encounter build issues during global installation, you can: -1. First build locally: `npm run build` -2. Then install globally: `npm install -g .` - -## Usage - -### Basic Example - -```javascript -const libCacheSim = require('./index'); - -// Run a simulation with default parameters -const result = libCacheSim.runSim(); -console.log(result); - -// Run a custom simulation -const customResult = libCacheSim.runSimulation( - '../data/trace.vscsi', // trace file path - 'vscsi', // trace type - 'lru', // cache algorithm - '10mb' // cache size -); -console.log(customResult); -``` - -### API Reference - -#### `runSimulation(tracePath, traceType, algorithm, cacheSize)` - -Run a cache simulation with custom parameters. - -**Parameters:** -- `tracePath` (string): Path to the trace file -- `traceType` (string): Type of trace file. Supported: `'vscsi'`, `'csv'`, `'txt'`, `'binary'`, `'oracle'` -- `algorithm` (string): Cache eviction algorithm. Supported: `'lru'`, `'fifo'`, `'lfu'`, `'arc'`, `'clock'`, `'s3fifo'`, `'sieve'` -- `cacheSize` (string): Cache size with unit. Examples: `'1mb'`, `'512kb'`, `'2gb'`, `'1024'` (bytes) - -**Returns:** -Object with simulation results: -```javascript -{ - totalRequests: 113872, // Total number of requests processed - hits: 15416, // Number of cache hits - misses: 98456, // Number of cache misses - hitRatio: 0.1354, // Cache hit ratio (0-1) - missRatio: 0.8646, // Cache miss ratio (0-1) - algorithm: 'lru', // Algorithm used - cacheSize: 1048576 // Cache size in bytes -} -``` - -#### `runSim()` - -Run a simulation with default parameters (backward compatibility). - -**Returns:** Same result object as `runSimulation()` - -#### `getSupportedAlgorithms()` - -Get list of supported cache algorithms. - -**Returns:** Array of algorithm names - -#### `getSupportedTraceTypes()` - -Get list of supported trace types. - -**Returns:** Array of trace type names - -### Examples - -#### Compare Different Algorithms - -```javascript -const libCacheSim = require('./index'); - -const algorithms = ['lru', 'fifo', 'lfu', 's3fifo']; -const tracePath = '../data/trace.vscsi'; -const cacheSize = '10mb'; - -algorithms.forEach(algo => { - const result = libCacheSim.runSimulation(tracePath, 'vscsi', algo, cacheSize); - console.log(`${algo.toUpperCase()}: Hit Ratio = ${result.hitRatio.toFixed(4)}`); -}); -``` - -#### Analyze Different Cache Sizes - -```javascript -const libCacheSim = require('./index'); - -const cacheSizes = ['1mb', '5mb', '10mb', '50mb', '100mb']; -const tracePath = '../data/trace.vscsi'; - -cacheSizes.forEach(size => { - const result = libCacheSim.runSimulation(tracePath, 'vscsi', 'lru', size); - console.log(`Size ${size}: Hit Ratio = ${result.hitRatio.toFixed(4)}`); -}); -``` - -### Error Handling - -The library throws JavaScript errors for common issues: - -```javascript -try { - const result = libCacheSim.runSimulation('/invalid/path', 'vscsi', 'lru', '1mb'); -} catch (error) { - console.error('Simulation failed:', error.message); -} -``` - -## Command Line Interface - -After global installation, you can use the `cachesim-js` command: - -### CLI Usage - -```bash -cachesim-js --trace --type --algorithm --size -``` - -### CLI Options - -- `--trace, -t `: Path to trace file (required) -- `--type `: Trace type (required) -- `--algorithm, -a `: Cache algorithm (required) -- `--size, -s `: Cache size (required) -- `--help, -h`: Show help message - -### CLI Examples - -```bash -# Basic simulation -cachesim-js -t trace.vscsi --type vscsi -a lru -s 10mb - -# Compare S3-FIFO with larger cache -cachesim-js --trace data.csv --type csv --algorithm s3fifo --size 50mb - -# Show help -cachesim-js --help -``` -## Development - -### Building from Source - -```bash -# Clean build -npm run clean -npm run build - -# Debug build with debugging symbols -DEBUG=1 npm run build -``` - -### Running Tests - -```bash -# Run test suite -npm test -``` \ No newline at end of file diff --git a/libCacheSim-node/package.json b/libCacheSim-node/package.json index 2b760079..80e60e08 100644 --- a/libCacheSim-node/package.json +++ b/libCacheSim-node/package.json @@ -1,6 +1,6 @@ { - "name": "@realtmxi/libcachesim-node", - "version": "1.0.0-test.5", + "name": "libcachesim-node", + "version": "1.0.0", "main": "index.js", "bin": { "cachesim-js": "./cli.js" @@ -25,9 +25,9 @@ "description": "Node.js bindings for libCacheSim - A high-performance cache simulator and analysis library supporting LRU, FIFO, S3-FIFO, Sieve and other caching algorithms", "repository": { "type": "git", - "url": "https://github.com/realtmxi/libCacheSim" + "url": "https://github.com/1a1a11a/libCacheSim" }, - "homepage": "https://github.com/realtmxi/libCacheSim/tree/npm-release/libCacheSim-node", + "homepage": "https://github.com/1a1a11a/libCacheSim/tree/main/libCacheSim-node", "bugs": { "url": "https://github.com/1a1a11a/libCacheSim/issues" }, @@ -53,7 +53,7 @@ "binary": { "module_name": "cachesim-addon", "module_path": "./build/Release/", - "remote_path": "https://github.com/realtmxi/libCacheSim/releases/download/", + "remote_path": "https://github.com/1a1a11a/libCacheSim/releases/download/", "package_name": "{module_name}-v{version}-{node_abi}-{platform}-{arch}.tar.gz" }, "publishConfig": { diff --git a/libCacheSim-node/test.cc b/libCacheSim-node/test.cc deleted file mode 100644 index 5b3eb97b..00000000 --- a/libCacheSim-node/test.cc +++ /dev/null @@ -1,28 +0,0 @@ -// test.cc -#include -#include "../libCacheSim/include/libCacheSim.h" - - -int main() { - std::cout << "Trying to include libCacheSim..." << std::endl; - - // Set up basic cache parameters - common_cache_params_t params = { - .cache_size = 1024 * 1024, // 1 MB cache - .default_ttl = 0, - .hashpower = 24 - }; - - // Try to create an LRU cache - cache_t* cache = LRU_init(params, nullptr); - - if (cache) { - std::cout << "Successfully created an LRU cache." << std::endl; - cache->cache_free(cache); // Proper cleanup - } else { - std::cerr << "Failed to create cache." << std::endl; - return 1; - } - - return 0; -} From 849c84b2ca4c814852517a6dd45a8bcfe4c37f24 Mon Sep 17 00:00:00 2001 From: Murphy Tian Date: Mon, 16 Jun 2025 16:23:00 +0800 Subject: [PATCH 5/7] [fix] support NPM RELEASE action on develop branch --- .github/workflows/npm-release.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/npm-release.yml b/.github/workflows/npm-release.yml index 4cba7bb3..843b8c91 100644 --- a/.github/workflows/npm-release.yml +++ b/.github/workflows/npm-release.yml @@ -5,7 +5,8 @@ on: types: [published] push: branches: - - main + - develop + - murphy/npm-release-0616 paths: - 'libCacheSim-node/**' From ed7559dad07d1f2f05e896fcd4b6597a971f32bb Mon Sep 17 00:00:00 2001 From: Murphy Tian Date: Mon, 16 Jun 2025 16:25:47 +0800 Subject: [PATCH 6/7] [fix] support NPM RELEASE action on develop branch --- .github/workflows/npm-release.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.github/workflows/npm-release.yml b/.github/workflows/npm-release.yml index 843b8c91..3c9e07d4 100644 --- a/.github/workflows/npm-release.yml +++ b/.github/workflows/npm-release.yml @@ -3,8 +3,15 @@ name: NPM Release on: release: types: [published] + workflow_dispatch: + inputs: + version: + description: 'Version to publish' + required: true + default: '1.0.0' push: branches: + - npm-release - develop - murphy/npm-release-0616 paths: From abf1ba2aea1a6fbb829ac02f6ce4d50e20355940 Mon Sep 17 00:00:00 2001 From: Murphy Tian Date: Mon, 16 Jun 2025 16:28:07 +0800 Subject: [PATCH 7/7] [fix] support NPM RELEASE action on develop branch --- .github/workflows/npm-release.yml | 8 -------- 1 file changed, 8 deletions(-) diff --git a/.github/workflows/npm-release.yml b/.github/workflows/npm-release.yml index 3c9e07d4..06de9b28 100644 --- a/.github/workflows/npm-release.yml +++ b/.github/workflows/npm-release.yml @@ -3,17 +3,9 @@ name: NPM Release on: release: types: [published] - workflow_dispatch: - inputs: - version: - description: 'Version to publish' - required: true - default: '1.0.0' push: branches: - - npm-release - develop - - murphy/npm-release-0616 paths: - 'libCacheSim-node/**'