{"id":16876447,"url":"https://github.com/raphaelsc/seastar","last_synced_at":"2025-03-19T04:43:33.406Z","repository":{"id":25815706,"uuid":"29254807","full_name":"raphaelsc/seastar","owner":"raphaelsc","description":null,"archived":false,"fork":false,"pushed_at":"2024-05-12T13:43:05.000Z","size":16091,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-25T03:44:42.528Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raphaelsc.png","metadata":{"files":{"readme":"README-OSv","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-01-14T16:53:56.000Z","updated_at":"2017-10-28T14:09:05.000Z","dependencies_parsed_at":"2024-11-25T04:25:08.689Z","dependency_job_id":"0d3db32c-f416-4d1d-aba7-ec4b5e6ae3a7","html_url":"https://github.com/raphaelsc/seastar","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelsc%2Fseastar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelsc%2Fseastar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelsc%2Fseastar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelsc%2Fseastar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raphaelsc","download_url":"https://codeload.github.com/raphaelsc/seastar/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244358337,"owners_count":20440355,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T15:39:28.501Z","updated_at":"2025-03-19T04:43:33.383Z","avatar_url":"https://github.com/raphaelsc.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"Running Seastar on OSv\n======================\n\n1. Compiling Seastar for OSv\n----------------------------\n\nBefore compiling Seastar, configure it with the following command:\n\n./configure.py --so --disable-hwloc \\\n    --cflags=\"-DDEFAULT_ALLOCATOR -fvisibility=default -DHAVE_OSV -I../osv/include\" \\\n    --mode release \n\nOr more easily, use the \"--with-osv=...\" shortcut for all the above settings:\n\n./configure.py --mode release --with-osv=../osv\n\n\nExplanation of these configuration options:\n   * The \"--so\" option is needed so that the Seastar applications, such as\n     httpd, are built as shared objects instead of ordinary executables.\n     Note the \"--pie\" option also exists, but because of bug #352 in OSv,\n     and the fact that Seastar uses thread_local in one place, these PIEs\n     cannot be run on OSv.\n   * The \"--disable-hwloc\" option is needed so that Seastar does not attempt\n     to use the complex NUMA-discovery library, which isn't supported on OSv\n     (and isn't relevant anyway, because VMs with NUMA are not (yet) common.\n   * The \"-DEFAULT_ALLOCATOR\" uses in Seastar the system's regular malloc()\n     and free(), instead of redefining them. Without this flag, what seems\n     to happen is that some code compiled into the OSv kernel (notably,\n     libboost_program_options.a) uses the standard malloc(), while inline\n     code compiled into Seastar uses the Seastar free() to try and free that\n     memory, resulting in a spectacular crash.\n   * The \"-fvisibility=default\" option disables the \"-fvisibility=hidden\"\n     option which is hard-coded into Seastar's build file. Supposedly\n     \"-fvisibility=hidden\" provides some better optimization in some cases,\n     but it also means OSv can't find main() in the generated shared object!\n     So either we use \"-fvisibility=default\", as suggested here, or\n     alternatively, make *only* main() visible - for example, to make httpd's\n     main() visible add in apps/httpd/httpd.cc, before the main() definition,\n     the chant: [[gnu::visibility(\"default\")]]\n   * The \"-DHAVE_OSV\" conditionally compiles code in Seastar that relies\n     on OSv APIs (currently, this enables virtio device assignment).\n     This OSv-specific code relies on some OSv header files, which is\n     why the \"-I../osv/include\" is needed (where \"../osv\" is where the\n     OSv source tree is open).\n   * The \"--mode release\" is to compile only the release build. You'll\n     usually not want to debug Seastar on OSv (it's easier to debug on Linux).\n\n\n2. Building a Seastar-httpd module for OSv\n------------------------------------------\n\nAs an example, we'll build a \"seastar\" module in OSv running Seastar's\nhttpd application.\n\nIn the OSv working directory, create a directory apps/seastar in it put:\n\n* a link to the httpd binary in the Seastar working directory. I.e.,\n  ln -s ../../../seastar/build/release/apps/httpd/httpd httpd\n\n* A usr.manifest file, adding only this single \"httpd\" executable to the image:\n  /httpd: ${MODULE_DIR}/httpd\n\n* A module.py file with a default command line:\n\n  from osv.modules import api\n  default = api.run(cmdline=\"/httpd --no-handle-interrupt\")  \n\nThe \"--no-handle-interrupt\" is needed so that Seastar does not attempt to\nuse signalfd() to capture ^C. signalfd is not yet available on OSv, and\nthe ^C handling is not a very important feature of Seastar anyway.\n\nAlso note that currently we cannot specify \"--network-stack=native\", because\nneither vhost nor a more efficient mechanism for \"virtio assignment\" is yet\ncomplete on OSv. So we must keep the default (which is \"--network-stack=posix\")\nwhich uses the OS's Posix networking APIs, which OSv fully supports.\n\n\n3. Running the seastar module on OSv\n-------------------------------------\n\nTo run the Seastar httpd application, using the module defined above, do,\nas usual, in the OSv working directory:\n\n$ make image=seastar -j4\n$ sudo scripts/run.py -nvV\n\nThis will open an HTTP server on port 10000 of the VM. For example, if the\nabove creates a VM with an IP address of 192.168.122.89, we can test it as\nfollowing:\n\n$ curl 192.168.122.89:10000 \n\u003chtml\u003e\u003chead\u003e\u003ctitle\u003ethis is the future\u003c/title\u003e\u003c/head\u003e\u003cbody\u003e\u003cp\u003eFuture!!\u003c/p\u003e\u003c/body\u003e\u003c/html\u003e\n\n4. Debugging OSv with the Seastar application\n---------------------------------------------\n\nIf you want to debug OSv (not the Seastar application) in relation to the\nway it runs Seastar, you'll want the \"httpd\" shared object to be available\nto gdb.\nUnfortunately, the object lookup code in \"osv syms\" (translate() in loader.py)\ndoes not seem to look for objects in apps/, so until we fix this, we need\nto put a link to httpd in a well-known place, such as build/release. So\ndo this in the OSv top directory:\n ln -s ../../apps/seastar/httpd build/release/httpd\n\nNote you'll need to repeat this if you do \"make clean\" (as \"make clean\"\nremoves everything in build/release).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraphaelsc%2Fseastar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraphaelsc%2Fseastar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraphaelsc%2Fseastar/lists"}