Getting Started
Briefly, Juptune is a library for the D programming language that focuses on providing @nogc nothrow implementations of common technologies and protocols, as well as an asynchronous multi-threaded event loop, for the ultimate purposes of being a batteries-included framework for building modern applications.
This page details how to get started with Juptune, and getting a basic example project running.
Juptune is a Linux only library, sorry!
Required System Libraries
Section titled “Required System Libraries”Your system must have libsodium >= 1.0.20 and openssl/libcrypto >= 3.5.0 preinstalled.
The libsodium dependency is pending removal in favour of going all in on openssl/libcrypto.
Installation
Section titled “Installation”Dub/redub
Section titled “Dub/redub”-
Open your existing dub project, or create a new one, and run:
Terminal window dub add juptune -
Use the following minimal code:
app.d void main(){import juptune.event : EventLoop, EventLoopConfig;auto loop = EventLoop(EventLoopConfig());loop.addNoGCThread(() @nogc nothrow {});loop.join();} -
Run the program, and hopefully it doesn’t crash:
Terminal window dub run
Meson (Global Install with pkgconfig)
Section titled “Meson (Global Install with pkgconfig)”-
Clone the repo (and optionally switch to a specific tag):
Terminal window git clone https://github.com/Juptune/juptune -
Setup a Meson build folder, with most of the optional stuff turned off:
Terminal window meson setup build --buildtype=release -Ddefault_library=static -Dbuild-unittests=false -Dbuild-integration-tests=false -Dbuild-examples=false -Dbuild-dasn1=false -Dbuild-dx509=false -
Run the following to install Juptune & its pkgconfig file globally:
Terminal window meson install -C build# (On some systems you'll need to do this instead)cd ./buildninja install # Potentially needs `sudo` -
(To undo the above installation):
Terminal window meson uninstall -C build# (On some systems you'll need to do this instead)cd ./buildninja uninstall # Potentially needs `sudo` -
In your Meson project, include Juptune as a dependency (it’ll be found via pkgconfig):
meson.build #### Project configuration ####project('basic-meson-project', 'd')#### Sources ####srcs = files('./src/main.d',)#### Dependencies ####juptune_dep = dependency('juptune')dep = declare_dependency(include_directories: include_directories('src'),sources: srcs,dependencies: [juptune_dep],)#### Executables ####main_exe = executable('basic-meson-project', dependencies: [dep], install: true)test_exe = executable('unittests', dependencies: [dep], d_unittest: true)#### Tests ####test('unittests', test_exe) -
Use the following minimal code that’ll be used to test that your setup works:
main.d void main(){import juptune.event : EventLoop, EventLoopConfig;auto loop = EventLoop(EventLoopConfig());loop.addNoGCThread(() @nogc nothrow {});loop.join();} -
Run the following commands and pray no errors show up:
Terminal window meson setup build --buildtype debugmeson compile -C build./build/basic-meson-project
Larger Example Code
Section titled “Larger Example Code”Here’s a larger piece of example code to run locally, to definitely make sure Juptune is running well on your system:
import juptune.core.util : Result, resultAssert;import juptune.dns : dnsLookupIp;import juptune.event : EventLoop, EventLoopConfig, IpAddress;import juptune.http : HttpClient, HttpClientConfig, HttpRequest, HttpResponse;
void main(){ auto loop = EventLoop(EventLoopConfig()); loop.addNoGCThread(() @nogc nothrow { /** This is still really bulky since some stuff is still TODO, e.g. HttpClient supporting DNS lookups natively; simpler GET and POST interface, etc. **/ IpAddress ip; dnsLookupIp("forum.dlang.org", ip).resultAssert;
auto client = HttpClient(HttpClientConfig()); client.connectTls(ip, "forum.dlang.org").resultAssert;
HttpRequest req; req.withPath("/"); req.withMethod("GET");
HttpResponse res; client.request(req, res).resultAssert;
import core.stdc.stdio : printf; printf("%d %s: Received %lld bytes from forum.dlang.org!", res.status, res.reason.slice.ptr, res.body.length); }); loop.join();}@gc or @nogc?
Section titled “@gc or @nogc?”Are you writing an application that:
- Needs absolute control of memory at all times?
- Uses a large amount of threads spread across large amounts of CPU cores, to such an extent that GC pauses have a notable impact?
If you’ve answered yes to either question: go with @nogc for your hot paths.
For all other cases go with @gc.
Next Steps
Section titled “Next Steps”Since Juptune is in alpha I’ve refrained from writing extensive “here’s some ideas you can try” guides as they’ll become outdated very quickly.
Instead, please review:
- The existing examples.
- The autogenerated API documentation.
- Start having a look over the hand-written Reference section - which you can find on the sidebar of this site - to get an idea of all the bells and whistles provided by Juptune.