Radeity commented on code in PR #262: URL: https://github.com/apache/incubator-hugegraph-doc/pull/262#discussion_r1218190128
########## content/cn/docs/contribution-guidelines/hugegraph-server-idea-setup.md: ########## @@ -0,0 +1,117 @@ +--- +title: "在 IDEA 中配置 HugeGraph-Server 开发环境" +linkTitle: "在 IDEA 中配置 HugeGraph-Server 开发环境" +weight: 4 +--- + +> 注意：下述配置仅供参考，基于[这个版本](https://github.com/apache/incubator-hugegraph/commit/a946ad1de4e8f922251a5241ffc957c33379677f)，在 Linux 和 macOS 平台下进行了测试。 + +### 背景 + +在 [Quick Start](/docs/quickstart/hugegraph-server/) 部分已经介绍了使用**脚本**启停 HugeGraphServer 的流程。下面以 Linux 平台为例，介绍使用 **IntelliJ IDEA** 运行与调试 HugeGraph-Server 的流程。 + +本地启动的核心与**脚本启动**是一样的： + +1. 初始化数据库后端，执行 `InitStore` 类初始化图 +2. 启动 HugeGraphServer，执行 `HugeGraphServer` 类加载初始化的图信息启动 + +在执行下述流程之前，请确保已经克隆了 HugeGraph 的源代码，并且已经配置了 JDK 11 等开发环境。 + +```bash +git clone https://github.com/apache/hugegraph.git +``` + +### 步骤 + +#### 1. 配置文件拷贝 + +为了避免配置文件的更改影响 Git 的追踪，建议将所需的配置文件拷贝到一个单独的文件夹中： + +```bash +cp -r hugegraph-dist/src/assembly/static/scripts hugegraph-dist/src/assembly/static/conf path-to-your-directory +``` + +#### 2. `InitStore` 类初始化图 + +首先，需要在配置文件中配置数据库后端。以 RocksDB 为例，在 `path-to/conf/graphs/hugegraph.properties` 文件中进行以下配置： + +```properties +backend=rocksdb +serializer=binary +rocksdb.data_path=. +rocksdb.wal_path=. +``` + +然后，打开 IntelliJ IDEA 的 `Run/Debug Configurations` 面板，创建一个新的 Application 配置，按照以下步骤进行配置： + +- 在 `Use classpath of module` 中选择 `hugegraph-dist` +- 将 `Main class` 设置为 `org.apache.hugegraph.cmd.InitStore` +- 设置运行参数为 `conf/graphs/hugegraph.properties`，这里的路径是相对于工作路径的，需要将工作路径设置为 `path-to-your-directory` + +配置完成后运行，如果运行成功，将会输出以下类似运行日志： + +```java +2023-06-05 00:43:37 [main] [INFO] o.a.h.u.ConfigUtil - Scanning option 'graphs' directory './conf/graphs' +2023-06-05 00:43:37 [main] [INFO] o.a.h.c.InitStore - Init graph with config file: ./conf/graphs/hugegraph.properties +...... +2023-06-05 00:43:39 [main] [INFO] o.a.h.b.s.r.RocksDBStore - Write down the backend version: 1.11 +2023-06-05 00:43:39 [main] [INFO] o.a.h.StandardHugeGraph - Graph 'hugegraph' has been initialized +2023-06-05 00:43:39 [main] [INFO] o.a.h.StandardHugeGraph - Close graph standardhugegraph[hugegraph] +2023-06-05 00:43:39 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStore - Opening RocksDB with data path: ./m +2023-06-05 00:43:39 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStore - Opening RocksDB with data path: ./s +2023-06-05 00:43:39 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStore - Opening RocksDB with data path: ./g +2023-06-05 00:43:39 [main] [INFO] o.a.h.HugeFactory - HugeFactory shutdown +2023-06-05 00:43:39 [hugegraph-shutdown] [INFO] o.a.h.HugeFactory - HugeGraph is shutting down +``` + +#### 3. `HugeGraphServer` 运行配置 + +类似地，打开 IntelliJ IDEA 的 `Run/Debug Configurations` 面板，创建一个新的 `Application` 配置，按照以下步骤进行配置： + +- 在 `Use classpath of module` 中选择 `hugegraph-dist` +- 将 `Main class` 设置为 `org.apache.hugegraph.dist.HugeGraphServer` +- 设置运行参数为 `conf/gremlin-server.yaml conf/rest-server.properties`，同样地，这里的路径是相对于工作路径的，需要将工作路径设置为 `<path-to-your-directory>` + +配置完成后运行，如果看到以下日志，表示 `HugeGraphServer` 已经成功启动： + +```java +...... +2023-06-05 00:51:56 [gremlin-server-boss-1] [INFO] o.a.t.g.s.GremlinServer - Gremlin Server configured with worker thread pool of 1, gremlin pool of 8 and boss thread pool of 1. +2023-06-05 00:51:56 [gremlin-server-boss-1] [INFO] o.a.t.g.s.GremlinServer - Channel started at port 8182. +``` + +#### 4. 调试 `HugeGraphServer` (可选) + +在完成上述配置后，可以尝试对 `HugeGraphServer` 进行调试。在调试模式下运行 `HugeGraphServer`，并在以下[位置](https://github.com/apache/hugegraph/blob/a946ad1de4e8f922251a5241ffc957c33379677f/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/VertexAPI.java#L238)设置断点： + +```java +public String list(@Context GraphManager manager, + @PathParam("graph") String graph, @QueryParam("label") String label, + @QueryParam("properties") String properties, ......) { + // ignore log + Map<String, Object> props = parseProperties(properties); +``` + +然后，使用 RESTful API 请求 `HugeGraphServer`： + +```bash +curl "http://localhost:8080/graphs/hugegraph/graph/vertices"; | gunzip +``` + +此时，可以在调试器中查看详细的变量信息。 + +### 可能遇到的问题 + +*** java: package sun.misc does not exist *** + +原因可能是在使用 Java 11 编译时触发了交叉编译，导致项目中使用的 `sun.misc.Unsafe` 找不到符号。有两种解决方案可供选择： + +1. 在 IntelliJ IDEA 的 `Preferences` 中找到 `Java Compiler` 面板，然后关闭 `--release` 选项 (推荐) Review Comment: ```suggestion 1. 在 IntelliJ IDEA 的 `Preferences/Settings` 中找到 `Java Compiler` 面板，然后关闭 `--release` 选项 (推荐) ``` ########## content/en/docs/contribution-guidelines/hugegraph-server-idea-setup.md: ########## @@ -0,0 +1,123 @@ +--- +title: "How to Set Up HugeGraph-Server Development Environment in IDEA" +linkTitle: "How to Set Up HugeGraph-Server Development Environment in IDEA" +weight: 4 +--- + +> NOTE: The following configuration is for reference purposes only, and has been tested on Linux and macOS platforms based on [this version](https://github.com/apache/incubator-hugegraph/commit/a946ad1de4e8f922251a5241ffc957c33379677f). + +### Background + +The [Quick Start](/docs/quickstart/hugegraph-server/) section provides instructions on how to start and stop HugeGraphServer using **scripts**. In this guide, we will explain how to run and debug HugeGraph-Server on the Linux platform using **IntelliJ IDEA**. + +The core steps for local startup are the same as starting with **scripts**: + +1. Initialize the database backend by executing the `InitStore` class to initialize the graph. +2. Start HugeGraphServer by executing the `HugeGraphServer` class to load the initialized graph information and start the server. + +Before proceeding with the following process, make sure that you have cloned the source code of HugeGraph and have configured the development environment, such as JDK 11. + +```bash +git clone https://github.com/apache/hugegraph.git +cd hugegraph +``` + +### Steps + +#### 1. Copy Configuration Files + +To avoid the impact of configuration file changes on Git tracking, it is recommended to copy the required configuration files to a separate folder. Run the following command to copy the files: + +```bash +cp -r hugegraph-dist/src/assembly/static/scripts hugegraph-dist/src/assembly/static/conf <path-to-your-directory> +``` + +Replace `<path-to-your-directory>` with the path to the directory where you want to copy the files. + +#### 2. Configure `InitStore` + +First, you need to configure the database backend in the configuration files. In this example, we will use RocksDB. Open `<path-to-your-directory>/conf/graphs/hugegraph.properties` and configure it as follows: + +```properties +backend=rocksdb +serializer=binary +rocksdb.data_path=. +rocksdb.wal_path=. +``` + +Next, open the `Run/Debug Configurations` panel in IntelliJ IDEA and create a new Application configuration. Follow these steps for the configuration: + +- Select `hugegraph-dist` as the `Use classpath of module`. +- Set the `Main class` to `org.apache.hugegraph.cmd.InitStore`. +- Set the program arguments to `conf/graphs/hugegraph.properties`. Note that the path here is relative to the working directory, so make sure to set the working directory to `<path-to-your-directory>`. + +Once the configuration is completed, run it. If the execution is successful, the following runtime logs will be displayed: + +```java +2023-06-05 00:43:37 [main] [INFO] o.a.h.u.ConfigUtil - Scanning option 'graphs' directory './conf/graphs' +2023-06-05 00:43:37 [main] [INFO] o.a.h.c.InitStore - Init graph with config file: ./conf/graphs/hugegraph.properties +...... +2023-06-05 00:43:39 [main] [INFO] o.a.h.b.s.r.RocksDBStore - Write down the backend version: 1.11 +2023-06-05 00:43:39 [main] [INFO] o.a.h.StandardHugeGraph - Graph 'hugegraph' has been initialized +2023-06-05 00:43:39 [main] [INFO] o.a.h.StandardHugeGraph - Close graph standardhugegraph[hugegraph] +2023-06-05 00:43:39 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStore - Opening RocksDB with data path: ./m +2023-06-05 00:43:39 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStore - Opening RocksDB with data path: ./s +2023-06-05 00:43:39 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStore - Opening RocksDB with data path: ./g +2023-06-05 00:43:39 [main] [INFO] o.a.h.HugeFactory - HugeFactory shutdown +2023-06-05 00:43:39 [hugegraph-shutdown] [INFO] o.a.h.HugeFactory - HugeGraph is shutting down +``` + +#### 3. Configure `HugeGraphServer` + +Similarly, open the `Run/Debug Configurations` panel in IntelliJ IDEA and create a new `Application` configuration. Follow these steps for the configuration: + +- Select `hugegraph-dist` as the `Use classpath of module`. +- Set the `Main class` to `org.apache.hugegraph.dist.HugeGraphServer`. +- Set the program arguments to `conf/gremlin-server.yaml conf/rest-server.properties`. Similarly, note that the path here is relative to the working directory, so make sure to set the working directory to `<path-to-your-directory>`. + +Once the configuration is completed, run it. If you see the following logs, it means that `HugeGraphServer` has been successfully started: + +```java +...... +2023-06-05 00:51:56 [gremlin-server-boss-1] [INFO] o.a.t.g.s.GremlinServer - Gremlin Server configured with worker thread pool of 1, gremlin pool of 8 and boss thread pool of 1. +2023-06-05 00:51:56 [gremlin-server-boss-1] [INFO] o.a.t.g.s.GremlinServer - Channel started at port 8182. +``` + +#### 4. Debugging `HugeGraphServer` (optional) + +After completing the above configuration, you can try debugging `HugeGraphServer`. Run `HugeGraphServer` in debug mode and set a breakpoint at the following [location](https://github.com/apache/hugegraph/blob/a946ad1de4e8f922251a5241ffc957c33379677f/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/VertexAPI.java#L238): + +```java +public String list(@Context GraphManager manager, + @PathParam("graph") String graph, + @QueryParam("label") String label, + @QueryParam("properties") String properties, + ......) { + ...... + + Map<String, Object> props = parseProperties(properties); +``` + +Then use the RESTful API to request `HugeGraphServer`: + +```bash +curl "http://localhost:8080/graphs/hugegraph/graph/vertices"; | gunzip +``` + +At this point, you can view detailed variable information in the debugger. + +### Possible Issues + +#### java: package sun.misc does not exist + +The reason may be that cross-compilation is triggered when using Java 11 to compile, causing the symbol of `sun.misc.Unsafe` used in the project to not be found. There are two possible solutions: + +1. In IntelliJ IDEA, go to `Preferences` and find the `Java Compiler` panel. Then, disable the `--release` option, or Review Comment: ```suggestion 1. In IntelliJ IDEA, go to `Preferences/Settings` and find the `Java Compiler` panel. Then, disable the `--release` option, or ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
