Skip to content

Commit 667951b

Browse files
alexander-penevalexander-penev
authored
Merge branch 'main' into MergeXeusClangRepl
2 parents aeb6b00 + eb4d98a commit 667951b

38 files changed

+58642
-755
lines changed

‎.readthedocs.yaml

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
version: 2
2+
3+
sphinx:
4+
configuration: docs/conf.py
5+
builder: html
6+
7+
build:
8+
os: "ubuntu-22.04"
9+
tools:
10+
python: "mambaforge-22.9"
11+
apt_packages:
12+
- clang-15
13+
- libclang-15-dev
14+
- llvm-15-dev
15+
- llvm-15-tools
16+
17+
conda:
18+
environment: docs/environment.yml

‎CMakeLists.txt

+30-3
Original file line numberDiff line numberDiff line change
@@ -122,16 +122,19 @@ endif ()
122122
include(CheckCXXCompilerFlag)
123123

124124
if (MSVC)
125-
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /wd4251 /wd4141")
126-
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /wd4018 /wd4267 /wd4715 /wd4146 /wd4129")
125+
add_compile_options(/wd4251 /wd4141)
126+
add_compile_options(/wd4018 /wd4267 /wd4715 /wd4146 /wd4129)
127+
add_compile_options(/EHsc)
128+
else()
129+
add_compile_options(-fexceptions)
127130
endif ()
128131

129132
if (CMAKE_CXX_COMPILER_ID MATCHES "Clang" OR
130133
CMAKE_CXX_COMPILER_ID MATCHES "GNU" OR
131134
CMAKE_CXX_COMPILER_ID MATCHES "Intel")
132135

133136
if(NOT XEUS_CPP_EMSCRIPTEN_WASM_BUILD)
134-
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wunused-parameter -Wextra -Wreorder")
137+
add_compile_options(-Wunused-parameter -Wextra -Wreorder)
135138
endif()
136139

137140
CHECK_CXX_COMPILER_FLAG("-std=c++17" HAS_CPP_17_FLAG)
@@ -149,6 +152,7 @@ if(XEUS_CPP_EMSCRIPTEN_WASM_BUILD)
149152
endif()
150153

151154
find_package(CppInterOp REQUIRED CONFIG PATHS "${CPPINTEROP_DIR}" "${CPPINTEROP_DIR}/lib")
155+
152156
find_package(argparse REQUIRED)
153157
find_package(pugixml REQUIRED)
154158
set(Python_FIND_VIRTUALENV ONLY)
@@ -426,6 +430,26 @@ configure_package_config_file(${PROJECT_NAME}Config.cmake.in
426430
"${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}Config.cmake"
427431
INSTALL_DESTINATION ${PROJECT_BINARY_DIR})
428432

433+
# Install xeus-cpp tag files
434+
set(XEUS_CPP_DATA_DIR "share/xeus-cpp" CACHE STRING "xeus-cpp data directory")
435+
set(XCPP_TAGFILES_DIR ${CMAKE_CURRENT_SOURCE_DIR}/share/xeus-cpp/tagfiles)
436+
install(DIRECTORY ${XCPP_TAGFILES_DIR}
437+
DESTINATION ${XEUS_CPP_DATA_DIR})
438+
439+
set(XEUS_CPP_CONF_DIR "etc/xeus-cpp" CACHE STRING "xeus-cpp configuration directory")
440+
set(XCPP_TAGCONFS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/etc/xeus-cpp/tags.d)
441+
install(DIRECTORY ${XCPP_TAGCONFS_DIR}
442+
DESTINATION ${XEUS_CPP_CONF_DIR})
443+
444+
# Add definitions for the kernel to find tagfiles.
445+
add_definitions(-DXCPP_TAGFILES_DIR="${CMAKE_INSTALL_PREFIX}/${XEUS_CPP_DATA_DIR}/tagfiles")
446+
if(CMAKE_INSTALL_PREFIX STREQUAL "/usr")
447+
# install into /etc instead of /usr/etc
448+
add_definitions(-DXCPP_TAGCONFS_DIR="/${XEUS_CPP_CONF_DIR}/tags.d")
449+
else()
450+
add_definitions(-DXCPP_TAGCONFS_DIR="${CMAKE_INSTALL_PREFIX}/${XEUS_CPP_CONF_DIR}/tags.d")
451+
endif()
452+
429453
# Configure 'xeus-cppConfig.cmake.in for an install tree
430454
set(XEUS_CPP_CONFIG_CODE "")
431455
configure_package_config_file(${PROJECT_NAME}Config.cmake.in
@@ -455,3 +479,6 @@ if(XEUS_CPP_EMSCRIPTEN_WASM_BUILD)
455479
DESTINATION ${CMAKE_INSTALL_BINDIR})
456480
endif ()
457481

482+
if(XEUS_CPP_INCLUDE_DOCS)
483+
add_subdirectory(docs)
484+
endif()

‎cmake/CreateSphinxTarget.cmake

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Implementation of 'create_sphinx_target' in this file is copied from
2+
# llvm implementation of 'AddSphinxTarget'.
3+
# https://github.com/llvm/llvm-project/blob/main/llvm/cmake/modules/AddSphinxTarget.cmake
4+
5+
find_package(Sphinx REQUIRED)
6+
7+
function(create_sphinx_target)
8+
cmake_parse_arguments(SPHINX
9+
"" # options
10+
"SOURCE_DIR;TARGET_NAME"
11+
"" # multi-value keywords
12+
${ARGN}
13+
)
14+
set(SPHINX_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/build)
15+
set(SPHINX_DOC_TREE_DIR ${CMAKE_CURRENT_BINARY_DIR}/_doctrees)
16+
17+
add_custom_target(${SPHINX_TARGET_NAME}
18+
COMMAND
19+
${SPHINX_EXECUTABLE} -b html -d ${SPHINX_DOC_TREE_DIR} -q ${SPHINX_SOURCE_DIR} ${SPHINX_BUILD_DIR}
20+
COMMENT
21+
"Generating sphinx user documentation into \"${SPHINX_BUILD_DIR}\""
22+
VERBATIM
23+
)
24+
message(STATUS "Added ${SPHINX_TARGET_NAME} target")
25+
endfunction()

‎cmake/FindSphinx.cmake

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# CMake find_package() Module for Sphinx documentation generator
2+
# http://sphinx-doc.org/
3+
#
4+
# Example usage:
5+
#
6+
# find_package(Sphinx)
7+
#
8+
# If successful the following variables will be defined
9+
# SPHINX_FOUND
10+
# SPHINX_EXECUTABLE
11+
12+
find_program(SPHINX_EXECUTABLE
13+
NAMES sphinx-build sphinx-build2
14+
DOC "Path to sphinx-build executable")
15+
16+
# Handle REQUIRED and QUIET arguments
17+
# this will also set SPHINX_FOUND to true if SPHINX_EXECUTABLE exists
18+
include(FindPackageHandleStandardArgs)
19+
find_package_handle_standard_args(Sphinx
20+
"Failed to locate sphinx-build executable"
21+
SPHINX_EXECUTABLE)
22+
23+
# Provide options for controlling different types of output
24+
option(SPHINX_OUTPUT_HTML "Output standalone HTML files" ON)
25+
option(SPHINX_OUTPUT_MAN "Output man pages" ON)
26+
27+
option(SPHINX_WARNINGS_AS_ERRORS "When building documentation treat warnings as errors" ON)

‎cmake/modules/GoogleTest.cmake

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
set(_gtest_byproduct_binary_dir
2+
${CMAKE_BINARY_DIR}/downloads/googletest-prefix/src/googletest-build)
3+
set(_gtest_byproducts
4+
${_gtest_byproduct_binary_dir}/lib/libgtest.a
5+
${_gtest_byproduct_binary_dir}/lib/libgtest_main.a
6+
${_gtest_byproduct_binary_dir}/lib/libgmock.a
7+
${_gtest_byproduct_binary_dir}/lib/libgmock_main.a
8+
)
9+
10+
if(MSVC)
11+
set(EXTRA_GTEST_OPTS
12+
-DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_DEBUG:PATH=${_gtest_byproduct_binary_dir}/lib/
13+
-DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_MINSIZEREL:PATH=${_gtest_byproduct_binary_dir}/lib/
14+
-DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_RELEASE:PATH=${_gtest_byproduct_binary_dir}/lib/
15+
-DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_RELWITHDEBINFO:PATH=${_gtest_byproduct_binary_dir}/lib/
16+
-Dgtest_force_shared_crt=ON
17+
BUILD_COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config Release)
18+
elseif(APPLE)
19+
set(EXTRA_GTEST_OPTS -DCMAKE_OSX_SYSROOT=${CMAKE_OSX_SYSROOT})
20+
endif()
21+
22+
include(ExternalProject)
23+
ExternalProject_Add(
24+
googletest
25+
GIT_REPOSITORY https://github.com/google/googletest.git
26+
GIT_SHALLOW 1
27+
GIT_TAG release-1.12.1
28+
UPDATE_COMMAND ""
29+
# # Force separate output paths for debug and release builds to allow easy
30+
# # identification of correct lib in subsequent TARGET_LINK_LIBRARIES commands
31+
# CMAKE_ARGS -DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_DEBUG:PATH=DebugLibs
32+
# -DCMAKE_ARCHIVE_OUTPUT_DIRECTORY_RELEASE:PATH=ReleaseLibs
33+
# -Dgtest_force_shared_crt=ON
34+
CMAKE_ARGS -G ${CMAKE_GENERATOR}
35+
-DCMAKE_BUILD_TYPE=Release
36+
-DCMAKE_C_COMPILER=${CMAKE_C_COMPILER}
37+
-DCMAKE_C_FLAGS=${CMAKE_C_FLAGS}
38+
-DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
39+
-DCMAKE_CXX_FLAGS=${CMAKE_CXX_FLAGS}
40+
-DCMAKE_AR=${CMAKE_AR}
41+
-DCMAKE_INSTALL_PREFIX=${CMAKE_INSTALL_PREFIX}
42+
${EXTRA_GTEST_OPTS}
43+
# Disable install step
44+
INSTALL_COMMAND ""
45+
BUILD_BYPRODUCTS ${_gtest_byproducts}
46+
# Wrap download, configure and build steps in a script to log output
47+
LOG_DOWNLOAD ON
48+
LOG_CONFIGURE ON
49+
LOG_BUILD ON
50+
TIMEOUT 600
51+
)
52+
53+
# Specify include dirs for gtest and gmock
54+
ExternalProject_Get_Property(googletest source_dir)
55+
set(GTEST_INCLUDE_DIR ${source_dir}/googletest/include)
56+
set(GMOCK_INCLUDE_DIR ${source_dir}/googlemock/include)
57+
# Create the directories. Prevents bug https://gitlab.kitware.com/cmake/cmake/issues/15052
58+
file(MAKE_DIRECTORY ${GTEST_INCLUDE_DIR} ${GMOCK_INCLUDE_DIR})
59+
60+
# Libraries
61+
ExternalProject_Get_Property(googletest binary_dir)
62+
set(_G_LIBRARY_PATH ${binary_dir}/lib/)
63+
64+
# Use gmock_main instead of gtest_main because it initializes gtest as well.
65+
# Note: The libraries are listed in reverse order of their dependancies.
66+
foreach(lib gtest gtest_main gmock gmock_main)
67+
add_library(${lib} IMPORTED STATIC GLOBAL)
68+
set_target_properties(${lib} PROPERTIES
69+
IMPORTED_LOCATION "${_G_LIBRARY_PATH}${CMAKE_STATIC_LIBRARY_PREFIX}${lib}${CMAKE_STATIC_LIBRARY_SUFFIX}"
70+
INTERFACE_INCLUDE_DIRECTORIES "${GTEST_INCLUDE_DIRS}"
71+
)
72+
add_dependencies(${lib} googletest)
73+
if("${CMAKE_CXX_COMPILER_ID}" STREQUAL "GNU" AND
74+
${CMAKE_CXX_COMPILER_VERSION} VERSION_GREATER_EQUAL 9)
75+
target_compile_options(${lib} INTERFACE -Wno-deprecated-copy)
76+
endif()
77+
endforeach()
78+
target_include_directories(gtest INTERFACE ${GTEST_INCLUDE_DIR})
79+
target_include_directories(gmock INTERFACE ${GMOCK_INCLUDE_DIR})
80+
81+
set_property(TARGET gtest PROPERTY IMPORTED_LOCATION ${_G_LIBRARY_PATH}/${CMAKE_STATIC_LIBRARY_PREFIX}gtest${CMAKE_STATIC_LIBRARY_SUFFIX})
82+
set_property(TARGET gtest_main PROPERTY IMPORTED_LOCATION ${_G_LIBRARY_PATH}/${CMAKE_STATIC_LIBRARY_PREFIX}gtest_main${CMAKE_STATIC_LIBRARY_SUFFIX})
83+
set_property(TARGET gmock PROPERTY IMPORTED_LOCATION ${_G_LIBRARY_PATH}/${CMAKE_STATIC_LIBRARY_PREFIX}gmock${CMAKE_STATIC_LIBRARY_SUFFIX})
84+
set_property(TARGET gmock_main PROPERTY IMPORTED_LOCATION ${_G_LIBRARY_PATH}/${CMAKE_STATIC_LIBRARY_PREFIX}gmock_main${CMAKE_STATIC_LIBRARY_SUFFIX})

‎docs/CMakeLists.txt

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
find_package(Doxygen REQUIRED)
2+
3+
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in)
4+
set(DOXYFILE ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg)
5+
6+
set(docs_srcdir ${CMAKE_CURRENT_SOURCE_DIR})
7+
set(docs_builddir ${CMAKE_CURRENT_BINARY_DIR})
8+
set(xeus_cpp_srcdir ${CMAKE_SOURCE_DIR})
9+
# file(READ ${CMAKE_SOURCE_DIR}/VERSION PACKAGE_VERSION)
10+
11+
configure_file(${DOXYFILE_IN} ${DOXYFILE} @ONLY)
12+
13+
add_custom_target(doxygen-xeus_cpp
14+
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE}
15+
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
16+
COMMENT "Generate xeus-cpp documentation with Doxygen"
17+
VERBATIM)
18+
19+
20+
list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
21+
include(CreateSphinxTarget)
22+
23+
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py
24+
${CMAKE_CURRENT_BINARY_DIR}/conf.py
25+
@ONLY
26+
)
27+
28+
create_sphinx_target(
29+
SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}
30+
TARGET_NAME sphinx-xeus-cpp
31+
)

‎docs/DevelopersDocumentation.rst

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Developers Documentation
2+
------------------------
3+
Xeus-cpp maintains an internal Doxygen documentation of its components. Internal
4+
documentation aims to capture intrinsic details and overall usage of code
5+
components. The goal of internal documentation is to make the codebase easier
6+
to understand for the new developers.
7+
8+
Internal documentation can be visited : `here </en/latest/build/html/index.html>`_

‎docs/Doxyfile

-13
This file was deleted.

‎docs/FAQ.rst

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
FAQ
2+
---
3+
4+
- **What is Xeus-cpp?**
5+
6+
Xeus-cpp is an interactive programming environment that allows you to
7+
execute C++ code in a Jupyter Notebook.
8+
9+
- **How do I install and build from source the Xeus-cpp?**
10+
11+
Installation instructions can be found in the project's documentation.
12+
You can follow the guide here: :doc:`Installation and usage <InstallationAndUsage>`
13+
14+
- **What are the benefits of using Xeus-cpp?**
15+
16+
You can interactively run and debug C++ code in a Jupyter notebook.
17+
18+
- Rapid Prototyping: Quickly prototype and experiment with C++ code without
19+
the need to create a full project or compile an entire codebase.
20+
- Immediate Feedback: As a REPL, xeus-cpp provides instant feedback as you
21+
write and execute code. This helps catch errors early.
22+
- Interactive Learning: Xeus-cpp allows learners to interactively
23+
explore C++ concepts and practice coding in a controlled environment.
24+
- Debugging: By isolating and testing specific pieces of code, you can more
25+
easily identify and fix issues in small code snippets.
26+
27+
- **How do I create a new session?**
28+
29+
To create a new Xeus-cpp session, simply open Jupyter Notebook,
30+
select the appropriate kernel, and create a new notebook file.
31+
32+
- **Where can I find documentation and examples for Xeus-cpp?**
33+
34+
Documentation, tutorials, and references can be found on this Documentation
35+
itself, :doc:`Documentation <DevelopersDocumentation>`.
36+
37+
- **How do I contribute to the project?**
38+
39+
Instructions for reporting issues and contributing to the project are
40+
provided in the repository's README or contributing guidelines.

‎docs/InstallationAndUsage.rst

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
InstallationAndUsage
2+
--------------------
3+
4+
You will first need to install dependencies.
5+
6+
.. code-block:: bash
7+
8+
mamba install cmake cxx-compiler xeus-zmq nlohmann_json cppzmq xtl jupyterlab
9+
clangdev=16 cpp-argparse pugixml -c conda-forge
10+
11+
12+
**Note:** Use a mamba environment with python version >= 3.11 for fetching clang-versions.
13+
14+
The safest usage is to create an environment named `xeus-cpp`.
15+
16+
.. code-block:: bash
17+
18+
mamba create -n xeus-cpp
19+
source activate xeus-cpp
20+
21+
Installing from conda-forge:
22+
Then you can install in this environment `xeus-cpp` and its dependencies.
23+
24+
.. code-block:: bash
25+
26+
mamba install xeus-cpp notebook -c conda-forge
27+
28+
mkdir build && cd build
29+
cmake .. -D CMAKE_PREFIX_PATH=$CONDA_PREFIX
30+
-D CMAKE_INSTALL_PREFIX=$CONDA_PREFIX -D CMAKE_INSTALL_LIBDIR=lib
31+
make && make install

0 commit comments

Comments
 (0)