diff --git a/doc/api/content/algo/getting-started/development.md b/doc/api/content/algo/getting-started/development.md index ae1b1d84a..1ffca3750 100644 --- a/doc/api/content/algo/getting-started/development.md +++ b/doc/api/content/algo/getting-started/development.md @@ -5,7 +5,7 @@ weight = 3 # Visual Studio Code -In this section we're going to use the Remote - Containers feature of Visual Studio Code to simplify the development experience. If you are using a different editor skip to the other editor section below. +In this section we're going to use the Remote - Containers feature of Visual Studio Code to simplify the development experience. If you are using a different editor skip to the other editor section below. ## Remote - Containers @@ -39,12 +39,99 @@ To debug your Algo set a breakpoint (F9) and open the Debug panel (Ctrl+Shift+D) -Now you can launch the Spark Client (spark_client.cmd) and it will connect to the running server. Log in with the user "bts" and no password and open a ladder. You can now select your Algo on the order type dropdown. +With sparkd running you can launch the Spark Client (spark_client.cmd) and it will connect to the running server. Log in with the user "bts" and no password and open a ladder. You can now select your Algo on the order type dropdown and activate it by clicking on a price on the ladder. +While sparkd is running you can also access the Spark Server Admin interface on [http://localhost:9000](http://localhost:9000). Use the same "bts" login to access the admin interface. Here you can manage user and account permissions and risk limits. + ## Starting Spark Server To start the Spark Server without attaching a debugger press "Ctrl+Shift+P" and select "Tasks: Run Task" and then "Start Sparkd" and "Never scan task output" This will open a new terminal where you can see any messages logged with the **Sdk** subsystem as well as any warnings or errors. To stop the Spark server simply kill the terminal (trash can icon) or run the "Stop Sparkd" task. -# Other Editor +## Next Steps + +If you would like to understand more about how Docker is working behind the scenes continue to the [next section](#other-editors). + +Otherwise, head over to the [Algo Lifecycle](/algo/ref/lifecycle/) section to understand how the IAlgoOrder can respond to events. + +
+ +# Other Editors + +In this section you will be more exposed to the details of how Docker works and how to compile and test your Algo using the command line. + +## Docker + +Spark Server is built and runs only on Linux so you need a Linux development environment to effectively develop plug-ins for it. Docker lets you take the spark_sdk.img disk image and run it inside a virtual Linux machine running on your Windows desktop. + +First, some terminology. A Docker "image" is a disk image containing a complete filesystem. The spark_sdk.img file you imported earlier is an image. A Docker "container" is what you get when you get when you attach this image to a running Linux system. You can connect to a running container and use it to run commands like the C++ compiler or the Spark server. Directories from your local filesystem can be mapped into the Docker container when it starts so you can easily share files. + +### Start + +The first step is to start the spark_sdk Docker container with the examples directory mapped so we can compile the examples inside the container. In your command prompt cd to the *examples* directory that you unzipped from the spark_sdk.zip file. Then run the following command to start the container. + +Windows Command Prompt: +{% clipable() %} +docker run --rm -it -v %CD%:/examples -u bts -w /examples --shm-size 1024m --name spark_sdk -h spark_sdk --cap-add=SYS_PTRACE --security-opt seccomp=unconfined -p 9000:9000 -p 9001:9001 spark_sdk bash +{% end %} + +**Powershell** / Linux / Mac: +{% clipable() %} +docker run --rm -it -v ${PWD}:/examples -u bts -w /examples --shm-size 1024m --name spark_sdk -h spark_sdk --cap-add=SYS_PTRACE --security-opt seccomp=unconfined -p 9000:9000 -p 9001:9001 spark_sdk bash +{% end %} + +### Attach + +The container will remain as long as this prompt is open. You can attach an additional to the running container with the following command: +{% clipable() %} +docker exec -it spark_sdk bash +{% end %} + +## Compiling + +Let's look at the algo_template sample first. All of the samples are laid out similarly with a `build.sh` script for compiling. As long as you are running build.sh inside the spark Docker container, it automatically copies the build output to /sparkbin/plugins/ where it needs to be to get loaded by the Spark server. + +``` +bts@spark_sdk:/examples$ cd algo_template/ +bts@spark_sdk:/examples/algo_template$ ./build.sh +algo_template.so copied to /sparkbin/plugins/ +Restart sparkd to see changes. +``` + +## Starting Spark Server + +To start the Spark server `cd /sparkbin/` and run `./sparkd run`. Press Ctrl+C to stop it. +``` +bts@spark_sdk:/sparkbin$ ./sparkd run +2019-10-25 16:21:09.383626|262552152803600|Gen|Warn |1 |main|132 |Run.cpp:53 |dev| +------------------------------------ Sparkd launched -------------------------------- +``` + +You will see any Sdk log messages as well as any log messages at or above Warning level from other parts of the system. If you need additional diagnostic information more details logs are stored in /sparkdata/data/logging/log. These logs will be automatically deleted when you stop the Docker container. + +With sparkd running you can launch the Spark Client (spark_client.cmd) and it will connect to the running server. Log in with the user "bts" and no password and open a ladder. You can now select your Algo on the order type dropdown and activate it by clicking on a price on the ladder. + + + +While sparkd is running you can also access the Spark Server Admin interface on [http://localhost:9000](http://localhost:9000). Use the same "bts" login to access the admin interface. Here you can manage user and account permissions and risk limits. + +## Debugging + +You can debug your algo using gdb from the bash command prompt. + +```bts@spark_sdk:/sparkbin$ gdb --args ./sparkd run +GNU gdb (Ubuntu 8.1-0ubuntu3) 8.1.0.20180409-git +Copyright (C) 2018 Free Software Foundation, Inc. +... +Reading symbols from ./sparkd...done. +(gdb) break algo_template.cpp:45 +No source file named algo_template.cpp. +Make breakpoint pending on future shared library load? (y or [n]) y +Breakpoint 1 (algo_template.cpp:45) pending. +(gdb) run +Starting program: /sparkbin/sparkd run +``` + +If your editor supports debugging over the ssh protocol you can configure and start sshd from inside the container. + diff --git a/doc/api/content/algo/getting-started/download.md b/doc/api/content/algo/getting-started/download.md index 8d612700e..d1df3af0d 100644 --- a/doc/api/content/algo/getting-started/download.md +++ b/doc/api/content/algo/getting-started/download.md @@ -16,15 +16,16 @@ Unzip that folder into a working directory. Inside you should see something like ``` spark_sdk.img client/ +spark_client.cmd examples/ ``` ## Import Import the spark_sdk image into docker using the `docker load` command. -``` +{% clipable() %} docker load < spark_sdk.img -``` +{% end %}
@@ -34,11 +35,11 @@ docker load < spark_sdk.img error during connect: Get http://%2F%2F.%2Fpipe%2Fdocker_engine/v1.40/images/json: open //./pipe/docker_engine: The system cannot find the file specified. In the default daemon configuration on Windows, the docker client must be run elevated to connect. This error may also indicate that the docker daemon is not running.
-Confirm that the image is loaded by running `docker images` which should list the new image. +Confirm that the import worked by running `docker images` which should list the new image. ``` c:\bts> docker images REPOSITORY TAG IMAGE ID CREATED SIZE -bluetradingsystems/spark_sdk latest a6dde8add63a 2 weeks ago 2.51GB +bluetradingsystems/spark_sdk latest e2be89436e73 4 hours ago 3.89GB ``` -## Control +## Activating the Algo Once loaded into the Spark server, your order type shows up in the Spark ladder, just like the in-box order types. @@ -22,5 +22,3 @@ If you are interested in sending orders to or otherwise controlling a Spark serv - - diff --git a/doc/api/templates/shortcodes/clipable.html b/doc/api/templates/shortcodes/clipable.html new file mode 100644 index 000000000..201b4fb75 --- /dev/null +++ b/doc/api/templates/shortcodes/clipable.html @@ -0,0 +1,15 @@ +
+ {{body}}
+