Skip to content

Commit c5fea06

Browse files
mcbartonmcbarton
authored
Update README.md + fix bug introduced into ci (compiler-research#91)
1 parent f2f5ff6 commit c5fea06

File tree

2 files changed

+212
-61
lines changed

2 files changed

+212
-61
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -467,14 +467,8 @@ jobs:
467467
cmake --build . --target clang clang-repl --parallel ${{ env.ncpus }}
468468
fi
469469
cd ../../
470-
#FIXME: Shouldn't be necessary to copy osx and Ubuntu differently
471-
OS=$(uname -s)
472-
if [[ "$OS" == "Darwin" ]]; then
473-
mkdir ./cppyy-backend/llvm-project/
474-
cp -r ./llvm-project/ ./cppyy-backend/llvm-project/
475-
else
476-
cp ./llvm-project/ ./cppyy-backend/
477-
fi
470+
mkdir ./cppyy-backend/llvm-project/
471+
cp -r ./llvm-project/ ./cppyy-backend/llvm-project/
478472
echo "Copy llvm-project folder to cppyy-backend for caching"
479473
480474
- name: Build LLVM/Cling on Windows systems if the cache is invalid
@@ -549,7 +543,9 @@ jobs:
549543
cmake --build . --config Release --target clang clang-repl --parallel ${{ env.ncpus }}
550544
}
551545
cd ../../
552-
cp -r .\llvm-project\ .\cppyy-backend\
546+
mkdir .\cppyy-backend\llvm-project\
547+
cp -r .\llvm-project\ .\cppyy-backend\llvm-project\
548+
echo "Copy llvm-project folder to cppyy-backend for caching"
553549
554550
- name: Save Cache LLVM/Clang runtime build directory
555551
uses: actions/cache/save@v3

‎README.md‎

Lines changed: 207 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,96 @@
11
# Setup cppyy for development
22

3-
## Installing the packages
3+
### Build Instructions (Includes instructions both Unix systems and Windows)
4+
Build instructions for CppInterOp and its dependencies are as follows. CppInterOP can be built with either Cling and Clang-REPL, so instructions will differ slightly depending on which option you would like to build, but should be clear from the section title which instructions to follow.
45

5-
### Install cling
6+
#### Clone CppInterOp and cppyy-backend
7+
First clone the CppInterOp repository, as this contains patches that need to be applied to the subsequently cloned llvm-project repo (these patches are only applied if building CppInterOp with Clang-REPL)
8+
```
9+
git clone --depth=1 https://github.com/compiler-research/CppInterOp.git
10+
```
11+
and clone cppyy-backend repository where we will be installing the CppInterOp library
12+
```
13+
git clone --depth=1 https://github.com/compiler-research/cppyy-backend.git
14+
```
615

7-
Build cling with LLVM and clang:
16+
#### Setup Clang-REPL
17+
Clone the 17.x release of the LLVM project repository.
18+
```
19+
git clone --depth=1 --branch release/17.x https://github.com/llvm/llvm-project.git
20+
cd llvm-project
21+
```
22+
Get the following patches required for development work. To apply these patches on Linux and MacOS execute the following command
23+
```
24+
git apply -v ../CppInterOp/patches/llvm/clang17-*.patch
25+
```
26+
and
27+
```
28+
cp -r ..\CppInterOp\patches\llvm\clang17* .
29+
git apply -v clang17-1-NewOperator.patch
30+
```
31+
on Windows.
832

33+
##### Build Clang-REPL
34+
Clang-REPL is an interpreter that CppInterOp works alongside. Build Clang (and
35+
Clang-REPL along with it). On Linux and MaxOS you do this by executing the following
36+
command
37+
```
38+
mkdir build
39+
cd build
40+
cmake -DLLVM_ENABLE_PROJECTS=clang \
41+
-DLLVM_TARGETS_TO_BUILD="host;NVPTX" \
42+
-DCMAKE_BUILD_TYPE=Release \
43+
-DLLVM_ENABLE_ASSERTIONS=ON \
44+
-DLLVM_USE_LINKER=lld \
45+
-DCLANG_ENABLE_STATIC_ANALYZER=OFF \
46+
-DCLANG_ENABLE_ARCMT=OFF \
47+
-DCLANG_ENABLE_FORMAT=OFF \
48+
-DCLANG_ENABLE_BOOTSTRAP=OFF \
49+
../llvm
50+
cmake --build . --target clang clang-repl --parallel $(nproc --all)
51+
```
52+
On Windows you would do this by executing the following
953
```
10-
git clone --depth=1 https://github.com/root-project/cling.git
54+
$env:ncpus = %NUMBER_OF_PROCESSORS%
55+
mkdir build
56+
cd build
57+
cmake -DLLVM_ENABLE_PROJECTS=clang `
58+
-DLLVM_TARGETS_TO_BUILD="host;NVPTX" `
59+
-DCMAKE_BUILD_TYPE=Release `
60+
-DLLVM_ENABLE_ASSERTIONS=ON `
61+
-DCLANG_ENABLE_STATIC_ANALYZER=OFF `
62+
-DCLANG_ENABLE_ARCMT=OFF `
63+
-DCLANG_ENABLE_FORMAT=OFF `
64+
-DCLANG_ENABLE_BOOTSTRAP=OFF `
65+
..\llvm
66+
cmake --build . --target clang clang-repl --parallel $env:ncpus
67+
```
68+
Note the 'llvm-project' directory location. On linux and MacOS you execute the following
69+
```
70+
cd ../
71+
export LLVM_DIR=$PWD
72+
cd ../
73+
```
74+
On Windows you execute the following
75+
```
76+
cd ..\
77+
$env:LLVM_DIR= $PWD.Path
78+
cd ..\
79+
```
80+
81+
#### Build Cling and related dependencies
82+
Besides the Clang-REPL interpreter, CppInterOp also works alongside the Cling
83+
interpreter. Cling depends on its own customised version of `llvm-project`,
84+
hosted under the `root-project` (see the git path below).
85+
Use the following build instructions to build on Linux and MacOS
86+
```
87+
git clone https://github.com/root-project/cling.git
88+
cd ./cling/
89+
git checkout tags/v1.0
90+
cd ..
1191
git clone --depth=1 -b cling-llvm13 https://github.com/root-project/llvm-project.git
12-
cd llvm-project
13-
mkdir build
14-
cd build
92+
mkdir llvm-project/build
93+
cd llvm-project/build
1594
cmake -DLLVM_ENABLE_PROJECTS=clang \
1695
-DLLVM_EXTERNAL_PROJECTS=cling \
1796
-DLLVM_EXTERNAL_CLING_SOURCE_DIR=../../cling \
@@ -28,57 +107,144 @@ cmake --build . --target clang --parallel $(nproc --all)
28107
cmake --build . --target cling --parallel $(nproc --all)
29108
cmake --build . --target gtest_main --parallel $(nproc --all)
30109
```
31-
32-
Note down the `llvm-project` directory location as we will need it later:
110+
Use the following build instructions to build on Windows
111+
```
112+
git clone https://github.com/root-project/cling.git
113+
cd .\cling\
114+
git checkout tags/v1.0
115+
cd ..
116+
git clone --depth=1 -b cling-llvm13 https://github.com/root-project/llvm-project.git
117+
$env:ncpus = %NUMBER_OF_PROCESSORS%
118+
$env:PWD_DIR= $PWD.Path
119+
$env:CLING_DIR="$env:PWD_DIR\cling"
120+
mkdir llvm-project\build
121+
cd llvm-project\build
122+
cmake -DLLVM_ENABLE_PROJECTS=clang `
123+
-DLLVM_EXTERNAL_PROJECTS=cling `
124+
-DLLVM_EXTERNAL_CLING_SOURCE_DIR="$env:CLING_DIR" `
125+
-DLLVM_TARGETS_TO_BUILD="host;NVPTX" `
126+
-DCMAKE_BUILD_TYPE=Release `
127+
-DLLVM_ENABLE_ASSERTIONS=ON `
128+
-DCLANG_ENABLE_STATIC_ANALYZER=OFF `
129+
-DCLANG_ENABLE_ARCMT=OFF `
130+
-DCLANG_ENABLE_FORMAT=OFF `
131+
-DCLANG_ENABLE_BOOTSTRAP=OFF `
132+
../llvm
133+
cmake --build . --target clang --parallel $env:ncpus
134+
cmake --build . --target cling --parallel $env:ncpus
135+
cmake --build . --target gtest_main --parallel $env:ncpus
136+
```
137+
Note the 'llvm-project' directory location. On linux and MacOS you execute the following
33138
```
34139
cd ../
35140
export LLVM_DIR=$PWD
36141
cd ../
37142
```
143+
On Windows you execute the following
144+
```
145+
cd ..\
146+
$env:LLVM_DIR= $PWD.Path
147+
cd ..\
148+
```
38149

39-
### Install CppInterOp
40-
41-
Clone the CppInterOp repo. Build it using cling and install. Note down the path
42-
to CppInterOp install directory. This will be referred to as `CPPINTEROP_DIR`:
150+
#### Environment variables
151+
Regardless of whether you are building CppInterOP with Cling or Clang-REPL you will need to define the following Envirnoment variables (as they clear for a new session, it is recommended that you also add these to your .bashrc in linux, .bash_profile if on MacOS, or profile.ps1 on Windows). On Linux and MacOS you define as follows
152+
```
153+
export CB_PYTHON_DIR="$PWD/cppyy-backend/python"
154+
export CPPINTEROP_DIR="$CB_PYTHON_DIR/cppyy_backend"
155+
export CPLUS_INCLUDE_PATH="${CPLUS_INCLUDE_PATH}:${LLVM_DIR}/llvm/include:${LLVM_DIR}/clang/include:${LLVM_DIR}/build/include:${LLVM_DIR}/build/tools/clang/include"
156+
export PYTHONPATH=$PYTHONPATH:$CPYCPPYY_DIR:$CB_PYTHON_DIR
157+
```
158+
If on MacOS you will also need the following envirnoment variable defined
159+
```
160+
export SDKROOT=`xcrun --show-sdk-path`
161+
```
162+
On Windows you define as follows (assumes you have defined $env:PWD_DIR= $PWD.Path )
163+
```
164+
$env:CB_PYTHON_DIR="$env:PWD_DIR\cppyy-backend\python"
165+
$env:CPPINTEROP_DIR="$env:CB_PYTHON_DIR\cppyy_backend"
166+
$env:CPLUS_INCLUDE_PATH="$env:CPLUS_INCLUDE_PATH;$env:LLVM_DIR\llvm\include;$env:LLVM_DIR\clang\include;$env:LLVM_DIR\build\include;$env:LLVM_DIR\build\tools\clang\include"
167+
$env:PYTHONPATH="$env:PYTHONPATH;$env:CPYCPPYY_DIR;$env:CB_PYTHON_DIR"
168+
```
43169

170+
#### Build CppInterOp
171+
Now CppInterOp can be installed. On Linux and MacOS execute
172+
```
173+
mkdir CppInterOp/build/
174+
cd CppInterOp/build/
175+
```
176+
On Windows execute
44177
```
45-
export CPPINTEROP_DIR=$PWD/cppyy-backend/python/cppyy_backend
178+
mkdir CppInterOp\build\
179+
cd CppInterOp\build\
46180
```
47181

182+
Now if you want to build CppInterOp with Clang-REPL then execute the following commands on Linux and MacOS
48183
```
49-
git clone https://github.com/compiler-research/CppInterOp.git
50-
cd CppInterOp
51-
mkdir build && cd build
52-
CPPINTEROP_BUILD_DIR=$(PWD)
53-
cmake -DBUILD_SHARED_LIBS=ON -DUSE_CLING=ON -DUSE_REPL=Off -DCling_DIR=$LLVM_DIR/build -DCMAKE_INSTALL_PREFIX=$CPPINTEROP_DIR ..
54-
cmake --build . --target install
184+
cmake -DBUILD_SHARED_LIBS=ON -DUSE_CLING=Off -DUSE_REPL=ON -DLLVM_DIR=$LLVM_DIR/build/lib/cmake/llvm -DClang_DIR=$LLVM_DIR/build/lib/cmake/clang -DCMAKE_INSTALL_PREFIX=$CPPINTEROP_DIR ..
185+
cmake --build . --target install --parallel $(nproc --all)
186+
```
187+
and
188+
```
189+
cmake -DUSE_CLING=Off -DUSE_REPL=ON -DLLVM_DIR=$LLVM_DIR\build\lib\cmake\llvm -DClang_DIR=$LLVM_DIR\build\lib\cmake\clang -DCMAKE_INSTALL_PREFIX=$env:CPPINTEROP_DIR ..
190+
cmake --build . --target install --parallel $env:ncpus
191+
```
192+
on Windows. If alternatively you would like to install CppInterOp with Cling then execute the following commands on Linux and MacOS
193+
```
194+
cmake -DBUILD_SHARED_LIBS=ON -DUSE_CLING=ON -DUSE_REPL=Off -DCling_DIR=$LLVM_DIR/build/tools/cling -DLLVM_DIR=$LLVM_DIR/build/lib/cmake/llvm -DClang_DIR=$LLVM_DIR/build/lib/cmake/clang -DCMAKE_INSTALL_PREFIX=$CPPINTEROP_DIR ..
195+
cmake --build . --target install --parallel $(nproc --all)
196+
```
197+
and
198+
```
199+
cmake -DUSE_CLING=ON -DUSE_REPL=Off -DCling_DIR=$LLVM_DIR\build\tools\cling -DLLVM_DIR=$LLVM_DIR\build\lib\cmake\llvm -DClang_DIR=$LLVM_DIR\build\lib\cmake\clang -DCMAKE_INSTALL_PREFIX=$env:CPPINTEROP_DIR ..
200+
cmake --build . --target install --parallel $env:ncpus
55201
```
56202

203+
#### Testing CppInterOp
204+
To test the built CppInterOp execute the following command in the CppInterOP build folder on Linux and MacOS
205+
```
206+
cmake --build . --target check-cppinterop --parallel $(nproc --all)
207+
```
208+
and
209+
```
210+
cmake --build . --target check-cppinterop --parallel $env:ncpus
211+
```
212+
on Windows. Now go back to the top level directory in which your building CppInterOP. On Linux and MacOS you do this by executing
213+
```
214+
cd ../..
215+
```
216+
and
217+
```
218+
cd ..\..
219+
```
220+
on Windows. Now you are in a position to install cppyy following the instructions below.
57221

58-
### Install cppyy-backend
222+
#### Building and Install cppyy-backend
59223

60224
Clone the repo, build it and copy library files into `python/cppyy-backend` directory:
61225

62226
```
63-
git clone https://github.com/compiler-research/cppyy-backend.git
64227
cd cppyy-backend
65-
mkdir -p python/cppyy_backend/lib build && cd build
66-
# Install CppInterOp first to appear in python/cppyy_backend/
67-
(cd $CPPINTEROP_BUILD_DIR && cmake --build . --target install)
68-
228+
mkdir -p python/cppyy_backend/lib build
229+
cd build
69230
cmake -DCppInterOp_DIR=$CPPINTEROP_DIR ..
70231
cmake --build .
232+
```
233+
If on a linux system now execute the following command
234+
```
71235
cp libcppyy-backend.so ../python/cppyy_backend/lib/
72236
```
237+
and if on MacOS execute the following command
238+
```
239+
cp libcppyy-backend.dylib ../python/cppyy_backend/lib/
240+
```
73241

74-
Note down the path to `cppyy-backend/python` directory as "CB_PYTHON_DIR":
242+
Note go back to the top level build directory
75243
```
76-
cd ../python
77-
export CB_PYTHON_DIR=$PWD
78244
cd ../..
79245
```
80246

81-
### Install CPyCppyy
247+
#### Install CPyCppyy
82248

83249
Create virtual environment and activate it:
84250
```
@@ -87,9 +253,9 @@ source .venv/bin/activate
87253
```
88254

89255
```
90-
git clone https://github.com/compiler-research/CPyCppyy.git
91-
cd CPyCppyy
92-
mkdir build && cd build
256+
git clone --depth=1 https://github.com/compiler-research/CPyCppyy.git
257+
mkdir CPyCppyy/build
258+
cd CPyCppyy/build
93259
cmake ..
94260
cmake --build .
95261
```
@@ -100,40 +266,29 @@ export CPYCPPYY_DIR=$PWD
100266
cd ../..
101267
```
102268

103-
### Install cppyy
269+
#### Install cppyy
104270

105271
```
106-
git clone https://github.com/compiler-research/cppyy.git
272+
git clone --depth=1 https://github.com/compiler-research/cppyy.git
107273
cd cppyy
108274
python -m pip install --upgrade . --no-deps
109275
cd ..
110276
```
111277

112-
## Run cppyy
278+
#### Run cppyy
113279

114280
Each time you want to run cppyy you need to:
115-
1. Activate the virtual environment
116-
```
117-
source .venv/bin/activate
118-
```
119-
2. Add `CPYCPPYY_DIR` and `CB_PYTHON_DIR` to `PYTHONPATH`:
120-
```
121-
export PYTHONPATH=$PYTHONPATH:$CPYCPPYY_DIR:$CB_PYTHON_DIR
122-
```
123-
The `CPYCPPYY_DIR` and `CB_PYTHON_DIR` will not be set if you start a new
124-
terminal instance so you can replace them with the actual path that they
125-
refer to.
126-
3. Add paths to `CPLUS_INCLUDE_PATH`
127-
```
128-
export CPLUS_INCLUDE_PATH="${CPLUS_INCLUDE_PATH}:${LLVM_DIR}/llvm/include:${LLVM_DIR}/clang/include:${LLVM_DIR}/build/include:${LLVM_DIR}/build/tools/clang/include"
129-
```
281+
Activate the virtual environment
282+
```
283+
source .venv/bin/activate
284+
```
130285

131286
Now you can `import cppyy` in `python`
132287
```
133288
python -c "import cppyy"
134289
```
135290

136-
## Run the tests
291+
#### Run cppyy tests
137292

138293
**Follow the steps in Run cppyy.** Change to the test directory, make the library files and run pytest:
139294
```

0 commit comments

Comments
 (0)