Skip to content

Commit 598d7d3

Browse files
realtmxi1a1a11a
realtmxi
and
1a1a11a
authored
npm public release with GitHub Actions (#193)
* [test] npm release with GitHub Actions * fix: solve merge confliction * Merge from npm-release to murphy/npm-release-0616 (#1) * [refactoring] modify test part code, delete unnecessary files * [fix] support NPM RELEASE action on develop branch * [fix] support NPM RELEASE action on develop branch * [fix] support NPM RELEASE action on develop branch --------- Co-authored-by: Juncheng Yang <1a1a11a@users.noreply.github.com>
1 parent 8bb69b9 commit 598d7d3

File tree

6 files changed

+400
-222
lines changed

6 files changed

+400
-222
lines changed

‎.github/workflows/npm-release.yml‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
name: NPM Release
2+
3+
on:
4+
release:
5+
types: [published]
6+
push:
7+
branches:
8+
- develop
9+
paths:
10+
- 'libCacheSim-node/**'
11+
12+
env:
13+
BUILD_TYPE: Release
14+
15+
jobs:
16+
create-release:
17+
runs-on: ubuntu-latest
18+
outputs:
19+
release_created: ${{ steps.release.outputs.release_created }}
20+
version: ${{ steps.package.outputs.version }}
21+
22+
steps:
23+
- name: Checkout code
24+
uses: actions/checkout@v4
25+
26+
- name: Get package version
27+
id: package
28+
working-directory: libCacheSim-node
29+
run: |
30+
VERSION=$(node -p "require('./package.json').version")
31+
echo "version=$VERSION" >> $GITHUB_OUTPUT
32+
echo "Version: $VERSION"
33+
34+
- name: Check if release exists
35+
id: check_release
36+
run: |
37+
VERSION="${{ steps.package.outputs.version }}"
38+
if gh release view "v$VERSION" > /dev/null 2>&1; then
39+
echo "Release v$VERSION already exists"
40+
echo "exists=true" >> $GITHUB_OUTPUT
41+
else
42+
echo "Release v$VERSION does not exist"
43+
echo "exists=false" >> $GITHUB_OUTPUT
44+
fi
45+
env:
46+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
47+
48+
- name: Create GitHub Release
49+
id: release
50+
if: steps.check_release.outputs.exists == 'false'
51+
uses: actions/create-release@v1
52+
env:
53+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
54+
with:
55+
tag_name: v${{ steps.package.outputs.version }}
56+
release_name: Release v${{ steps.package.outputs.version }}
57+
body: |
58+
Release v${{ steps.package.outputs.version }}
59+
60+
## Installation
61+
```bash
62+
npm install libcachesim-node
63+
```
64+
65+
## Supported Platforms
66+
- Linux x64
67+
68+
Pre-compiled binaries are automatically downloaded during installation.
69+
draft: false
70+
prerelease: false
71+
72+
build-and-publish:
73+
needs: create-release
74+
runs-on: ubuntu-latest
75+
76+
steps:
77+
- name: Checkout code
78+
uses: actions/checkout@v4
79+
with:
80+
fetch-depth: 0
81+
82+
- name: Setup Node.js
83+
uses: actions/setup-node@v4
84+
with:
85+
node-version: '18'
86+
registry-url: 'https://registry.npmjs.org'
87+
88+
- name: Install system dependencies
89+
run: |
90+
sudo apt-get update
91+
sudo apt-get install -y build-essential cmake libglib2.0-dev libzstd-dev
92+
93+
- name: Build libCacheSim
94+
run: |
95+
echo "Building libCacheSim for Linux x64..."
96+
mkdir -p _build
97+
cd _build
98+
cmake -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} .. -DCMAKE_VERBOSE_MAKEFILE=ON
99+
echo "Starting build..."
100+
make -j$(nproc) VERBOSE=1
101+
102+
- name: Prepare vendored library
103+
run: |
104+
mkdir -p libCacheSim-node/vendor/include
105+
cp _build/liblibCacheSim.a libCacheSim-node/vendor/
106+
cp -r libCacheSim/include/* libCacheSim-node/vendor/include/
107+
108+
- name: Install Node.js dependencies
109+
working-directory: libCacheSim-node
110+
run: npm install
111+
112+
- name: Build and upload prebuilt binary
113+
working-directory: libCacheSim-node
114+
run: |
115+
echo "Building Node.js addon for Linux x64..."
116+
echo "Node.js version: $(node --version)"
117+
echo "NPM version: $(npm --version)"
118+
ls -la ../
119+
ls -la ../_build/
120+
CFLAGS=-fPIC CXXFLAGS=-fPIC npx prebuild --upload-all --verbose
121+
env:
122+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
123+
124+
- name: Test binary
125+
working-directory: libCacheSim-node
126+
run: |
127+
echo "Testing binary load for Linux x64..."
128+
ls -la
129+
ls -la prebuilds/ || echo "No prebuilds directory found"
130+
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); }"
131+
132+
publish-npm:
133+
needs: build-and-publish
134+
runs-on: ubuntu-latest
135+
136+
steps:
137+
- name: Checkout code
138+
uses: actions/checkout@v4
139+
140+
- name: Setup Node.js
141+
uses: actions/setup-node@v4
142+
with:
143+
node-version: '18'
144+
registry-url: 'https://registry.npmjs.org'
145+
146+
- name: Install system dependencies
147+
run: |
148+
sudo apt-get update
149+
sudo apt-get install -y build-essential cmake libglib2.0-dev libzstd-dev
150+
151+
- name: Build libCacheSim
152+
run: |
153+
mkdir -p _build
154+
cd _build
155+
cmake -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} ..
156+
make -j$(nproc)
157+
158+
- name: Prepare vendored library
159+
run: |
160+
mkdir -p libCacheSim-node/vendor/include
161+
cp _build/liblibCacheSim.a libCacheSim-node/vendor/
162+
cp -r libCacheSim/include/* libCacheSim-node/vendor/include/
163+
164+
- name: Publish to NPM
165+
working-directory: libCacheSim-node
166+
run: npm publish --access public
167+
env:
168+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎libCacheSim-node/README.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# libCacheSim Node.js Bindings
2+
3+
Node.js bindings for libCacheSim - A high-performance cache simulator and analysis library supporting LRU, FIFO, S3-FIFO, Sieve and other caching algorithms.
4+
5+
## Features
6+
7+
- **High Performance**: Built on the optimized libCacheSim C library
8+
- **Multiple Algorithms**: Support for LRU, FIFO, LFU, ARC, Clock, S3-FIFO, Sieve, and more
9+
- **Various Trace Types**: Support for vscsi, csv, txt, binary, and oracle trace formats
10+
- **Pre-compiled Binaries**: Fast installation with no build tools required
11+
- **Cross-platform**: Support for Linux (x64) and macOS (x64, ARM64)
12+
13+
## Installation
14+
15+
```bash
16+
npm install libcachesim-node
17+
```
18+
19+
The package includes pre-compiled binaries for supported platforms. No additional build tools or dependencies are required for end users.
20+
21+
### Supported Platforms
22+
23+
- **Linux**: x64 (Ubuntu 18.04+, other distributions with compatible glibc)
24+
- **macOS**: x64 (Intel) and ARM64 (Apple Silicon)
25+
26+
If pre-compiled binaries are not available for your platform, please check the releases page for updates or submit an issue.
27+
28+
## Quick Start
29+
30+
```javascript
31+
const { runSimulation, getSupportedAlgorithms } = require('libcachesim-node');
32+
33+
// Get supported algorithms
34+
console.log('Supported algorithms:', getSupportedAlgorithms());
35+
36+
// Run a cache simulation
37+
const result = runSimulation(
38+
'/path/to/trace.vscsi', // Path to trace file
39+
'vscsi', // Trace type
40+
's3fifo', // Cache algorithm
41+
'1mb' // Cache size
42+
);
43+
44+
console.log('Simulation results:', result);
45+
```
46+
47+
## API Reference
48+
49+
### `runSimulation(tracePath, traceType, algorithm, cacheSize)`
50+
51+
Run a cache simulation with specified parameters.
52+
53+
**Parameters:**
54+
- `tracePath` (string): Path to the trace file
55+
- `traceType` (string): Type of trace file ('vscsi', 'csv', 'txt', 'binary', 'oracle')
56+
- `algorithm` (string): Cache replacement algorithm
57+
- `cacheSize` (string): Cache size (e.g., '1mb', '512kb', '2gb')
58+
59+
**Returns:** Object containing simulation results including hit rate, miss count, etc.
60+
61+
### `getSupportedAlgorithms()`
62+
63+
Get a list of supported cache algorithms.
64+
65+
**Returns:** Array of algorithm names
66+
67+
### `getSupportedTraceTypes()`
68+
69+
Get a list of supported trace file types.
70+
71+
**Returns:** Array of trace type names
72+
73+
## Cache Algorithms
74+
75+
The following cache replacement algorithms are supported:
76+
77+
- **LRU** (Least Recently Used)
78+
- **FIFO** (First In, First Out)
79+
- **LFU** (Least Frequently Used)
80+
- **ARC** (Adaptive Replacement Cache)
81+
- **Clock** (Clock/Second Chance)
82+
- **S3-FIFO** (Simple, Scalable, Scan-resistant FIFO)
83+
- **Sieve** (Eviction algorithm with lazy promotion)
84+
85+
## Trace File Formats
86+
87+
- **vscsi**: VMware vSCSI trace format
88+
- **csv**: Comma-separated values format
89+
- **txt**: Plain text format
90+
- **binary**: Binary trace format
91+
- **oracle**: Oracle optimal algorithm simulation
92+
93+
## Command Line Interface
94+
95+
The package includes a command-line interface:
96+
97+
```bash
98+
# Install globally for CLI access
99+
npm install -g libcachesim-node
100+
101+
# Run simulation from command line
102+
cachesim-js --trace /path/to/trace.vscsi --algorithm s3fifo --size 1mb
103+
```
104+
105+
## Development
106+
107+
### Building from Source
108+
109+
If you need to build from source or contribute to development:
110+
111+
```bash
112+
# Clone the repository
113+
git clone https://github.com/1a1a11a/libCacheSim.git
114+
cd libCacheSim/libCacheSim-node
115+
116+
# Install dependencies
117+
npm install
118+
119+
# Build from source (requires cmake, build tools)
120+
npm run build-from-source
121+
122+
# Run tests
123+
npm test
124+
```
125+
126+
### Requirements for Building from Source
127+
128+
- Node.js 14+
129+
- CMake 3.10+
130+
- C/C++ compiler (GCC, Clang, or MSVC)
131+
- System dependencies:
132+
- Linux: `build-essential cmake libglib2.0-dev libzstd-dev`
133+
- macOS: `cmake glib zstd` (via Homebrew)
134+
135+
## Architecture
136+
137+
This package uses `prebuild-install` for binary distribution:
138+
139+
1. **Pre-compiled Binaries**: Automatically downloaded from GitHub releases during installation
140+
2. **Automated Building**: GitHub Actions automatically builds binaries for all supported platforms
141+
3. **Standard Tooling**: Uses industry-standard `prebuild` and `prebuild-install` packages
142+
143+
## Troubleshooting
144+
145+
### Installation Issues
146+
147+
If installation fails, try the following:
148+
149+
```bash
150+
# Clear npm cache
151+
npm cache clean --force
152+
153+
# Reinstall with verbose logging
154+
npm install libcachesim-node --verbose
155+
156+
# Force source compilation
157+
npm install libcachesim-node --build-from-source
158+
```
159+
160+
### Binary Loading Issues
161+
162+
If you see binary loading errors:
163+
164+
1. Ensure your platform is supported
165+
2. Check that the `prebuilds` directory exists and contains your platform's binary
166+
3. Try reinstalling the package
167+
4. Check Node.js version compatibility (requires Node.js 14+)
168+
169+
### Build from Source Issues
170+
171+
If source compilation fails:
172+
173+
1. Install required system dependencies
174+
2. Ensure CMake 3.10+ is available
175+
3. Check that libCacheSim builds successfully: `cd .. && mkdir _build && cd _build && cmake .. && make`
176+
177+
## Contributing
178+
179+
Contributions are welcome! Please see the main [libCacheSim repository](https://github.com/1a1a11a/libCacheSim) for contribution guidelines.
180+
181+
## License
182+
183+
MIT License - see the LICENSE file for details.
184+
185+
## Related Projects
186+
187+
- [libCacheSim](https://github.com/1a1a11a/libCacheSim) - The core C library
188+
- [libCacheSim Python bindings](https://github.com/1a1a11a/libCacheSim/tree/develop/libCacheSim/pyBindings) - Python interface
189+
190+
## Citation
191+
192+
If you use libCacheSim in your research, please cite:
193+
194+
```bibtex
195+
@misc{libcachesim,
196+
title={libCacheSim: A High-Performance Cache Simulator},
197+
author={Tian, Murphy and others},
198+
year={2023},
199+
url={https://github.com/1a1a11a/libCacheSim}
200+
}
201+
```

0 commit comments

Comments
 (0)