pystorm/BUILD.md

Build Instructions

Building StormLib for PyStorm

PyStorm requires the StormLib shared library. You can either:

1. Build it automatically using the provided script
2. Build it manually
3. Use a system-wide installation

Option 1: Automatic Build (Recommended)

# Build StormLib and embed it in the package
python3 build_stormlib.py

# Then install PyStorm
pip install -e .

The build script will:

• Clone StormLib from GitHub
• Compile it using CMake
• Copy the compiled library to the pystorm/ package directory

Option 2: Manual Build

Prerequisites

• git: For cloning repositories
• cmake: Build system (version 3.10+)
• C/C++ compiler: GCC, Clang, or MSVC

Linux/macOS

# Install prerequisites
# Ubuntu/Debian:
sudo apt-get install git cmake build-essential

# macOS:
brew install cmake

# Clone StormLib
git clone https://github.com/ladislav-zezula/StormLib.git
cd StormLib

# Build
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON
cmake --build . --config Release

# Copy library to PyStorm package
cd ../../
cp StormLib/build/libstorm.so* pystorm/  # Linux
# or
cp StormLib/build/libstorm.dylib pystorm/  # macOS

# Install PyStorm
pip install -e .

Windows

# Install prerequisites
# - Install Visual Studio with C++ support
# - Install CMake from https://cmake.org/

# Clone StormLib
git clone https://github.com/ladislav-zezula/StormLib.git
cd StormLib

# Build
mkdir build
cd build
cmake .. -DBUILD_SHARED_LIBS=ON
cmake --build . --config Release

# Copy library to PyStorm package
cd ..\..\
copy StormLib\build\Release\StormLib.dll pystorm\

# Install PyStorm
pip install -e .

Option 3: System-Wide Installation

Install StormLib to system library paths:

Linux

git clone https://github.com/ladislav-zezula/StormLib.git
cd StormLib
mkdir build && cd build
cmake ..
make
sudo make install
sudo ldconfig

# Then install PyStorm
pip install pystorm

macOS

git clone https://github.com/ladislav-zezula/StormLib.git
cd StormLib
mkdir build && cd build
cmake ..
make
sudo make install

# Then install PyStorm
pip install pystorm

Windows

Build StormLib and copy the DLL to:

• C:\Windows\System32\ (system-wide)
• Or the Python Scripts directory
• Or keep it with your application

Verification

Test that everything works:

import pystorm
print(pystorm.__version__)

# Try basic operations
from pystorm import MPQArchive
print("PyStorm is ready to use!")

Troubleshooting

Library Not Found

If you get "StormLib not loaded" error:

1. Check package directory: Ensure library is in pystorm/ directory

   ls pystorm/*.so      # Linux
   ls pystorm/*.dylib   # macOS
   dir pystorm\*.dll    # Windows
   

2. Check system paths: Ensure library is in library path

   ldconfig -p | grep storm    # Linux
   otool -L pystorm/libstorm.dylib  # macOS (to check dependencies)
   

3. Set library path (temporary):

   export LD_LIBRARY_PATH=/path/to/pystorm:$LD_LIBRARY_PATH  # Linux
   export DYLD_LIBRARY_PATH=/path/to/pystorm:$DYLD_LIBRARY_PATH  # macOS
   

Build Failures

CMake not found:

# Linux
sudo apt-get install cmake

# macOS
brew install cmake

# Windows
# Download from https://cmake.org/

Compiler not found:

# Linux
sudo apt-get install build-essential

# macOS
xcode-select --install

# Windows
# Install Visual Studio with C++ support

Git not found:

# Linux
sudo apt-get install git

# macOS
brew install git

# Windows
# Download from https://git-scm.com/

Platform-Specific Notes

Linux

• Library name: libstorm.so or libstorm.so.X.X.X
• May need sudo ldconfig after system-wide install
• Compatible with most distributions

macOS

• Library name: libstorm.dylib
• Minimum deployment target: macOS 10.13
• May need to sign library for distribution

Windows

• Library name: StormLib.dll
• Requires Visual Studio runtime
• May need to copy additional DLLs

Creating Distributable Packages

To create a wheel with embedded library:

# Build the library
python3 build_stormlib.py

# Build wheel
pip install build
python3 -m build

# Result: dist/pystorm-1.0.0-py3-none-any.whl

The wheel will include the compiled library and can be distributed.

Docker Build Example

FROM python:3.11-slim

# Install build dependencies
RUN apt-get update && apt-get install -y \
    git cmake build-essential \
    && rm -rf /var/lib/apt/lists/*

# Clone and install PyStorm
RUN git clone https://github.com/enne2/pystorm.git
WORKDIR /pystorm

# Build StormLib
RUN python3 build_stormlib.py

# Install PyStorm
RUN pip install -e .

# Verify installation
RUN python3 -c "import pystorm; print(pystorm.__version__)"

License

StormLib is licensed under the MIT License by Ladislav Zezula. PyStorm is also MIT licensed.