docs: client onboarding kit — Studio launcher, quick start, migration guide#90
Conversation
… guide
Round out the adoption story for people coming from Advantage (ADS) on
the client side: an extracted release should be usable without reading
the full README.
- openads-studio.{bat,sh}: one-click launcher that starts the engine
with the web console and opens the browser — the ARC replacement,
zero config. Uses an ephemeral wire port (--port 0) so it never
clashes with an Advantage service on 6262.
- QUICKSTART.md: the three paths in the box — drop-in DLL for a local
app, Studio for browsing/editing, openads_serverd for a network
server.
- docs/{en,pt,es}/migrating-from-ads: concept-by-concept map (server,
Local Server, client DLL, ARC, ads.cfg, ports) with a checklist.
Names of the legacy product are used only descriptively, for
nominative compatibility, with a trademark/non-affiliation note; no
third-party brand is claimed.
To ship these files inside the release archive, add a copy of
QUICKSTART.md + openads-studio.{sh,bat} (and openads.ini.sample once
the --config PR lands) to the staging steps in
.github/workflows/release.yml — left out of this PR so it touches no CI.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds quick start documentation, migration guides from ADS in English, Spanish, and Portuguese, and launcher scripts for OpenADS Studio on Windows and Unix-like systems. The feedback focuses on fixing a potential command-line parsing issue in the Windows batch script when paths end with a backslash, improving the robustness of the shell script with process cleanup and startup checks, and correcting several broken relative links in the Spanish and Portuguese translation files.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| set "DATA=%CD%" | ||
| if not "%~1"=="" set "DATA=%~1" |
There was a problem hiding this comment.
In Windows batch files, if a path ends with a backslash (such as a drive root like C:\ or a user-provided path with a trailing backslash), passing it inside double quotes like --data "%DATA%" will result in the trailing backslash escaping the closing double quote (i.e., \"). This causes command-line parsing to fail. Appending an extra backslash when a trailing backslash is detected (making it \\) resolves this, as the Windows command-line parser treats \\" as a single literal backslash and a closing quote.
set "DATA=%CD%"
if not "%~1"=="" set "DATA=%~1"
if "%DATA:~-1%"=="\" set "DATA=%DATA%\"
| "$DIR/openads_serverd" --port 0 --http-port "$HTTP_PORT" --data "$DATA" & | ||
| SRV=$! | ||
|
|
||
| # give the server a moment to bind, then open the browser (best effort) | ||
| sleep 1 | ||
| (xdg-open "http://127.0.0.1:${HTTP_PORT}/" 2>/dev/null \ | ||
| || open "http://127.0.0.1:${HTTP_PORT}/" 2>/dev/null \ | ||
| || true) |
There was a problem hiding this comment.
To make the launcher script more robust, we should:
- Add an
EXITtrap to clean up the background server process (openads_serverd) when the script exits or is terminated, preventing orphaned processes. - Check if the server successfully started (using
kill -0) before attempting to open the browser, avoiding opening a dead page if the port is already in use.
| "$DIR/openads_serverd" --port 0 --http-port "$HTTP_PORT" --data "$DATA" & | |
| SRV=$! | |
| # give the server a moment to bind, then open the browser (best effort) | |
| sleep 1 | |
| (xdg-open "http://127.0.0.1:${HTTP_PORT}/" 2>/dev/null \ | |
| || open "http://127.0.0.1:${HTTP_PORT}/" 2>/dev/null \ | |
| || true) | |
| "$DIR/openads_serverd" --port 0 --http-port "$HTTP_PORT" --data "$DATA" & | |
| SRV=$! | |
| trap 'kill "$SRV" 2>/dev/null || true' EXIT | |
| # give the server a moment to bind, then open the browser (best effort) | |
| sleep 1 | |
| if kill -0 "$SRV" 2>/dev/null; then | |
| (xdg-open "http://127.0.0.1:${HTTP_PORT}/" 2>/dev/null \\ | |
| || open "http://127.0.0.1:${HTTP_PORT}/" 2>/dev/null \\ | |
| || true) | |
| else | |
| echo "Error: openads_serverd failed to start." >&2 | |
| exit 1 | |
| fi |
| Para una compilación nueva, use la import lib de su compilador en `lib/` (MSVC, | ||
| MinGW, Borland). Binarios heredados enlazados por ordinal: vea | ||
| [`../en/ordinal-compat.md`](../en/ordinal-compat.md). Detalles de RDD: | ||
| [`rddads-compat.md`](rddads-compat.md). |
There was a problem hiding this comment.
The link to rddads-compat.md is broken because it resolves to docs/es/rddads-compat.md, which does not exist. It should point to the English version in docs/en/ using a relative path, similar to how ordinal-compat.md is linked.
| [`rddads-compat.md`](rddads-compat.md). | |
| [../en/rddads-compat.md](../en/rddads-compat.md). |
| (reindex, pack, zap) y crear/editar objetos del diccionario (tablas, usuarios, | ||
| índices, reglas de RI). Protéjalo con `--http-user usuario:clave`; para | ||
| exposición pública ponga un proxy TLS delante (vea | ||
| [`servicio-despliegue.md`](servicio-despliegue.md)). |
There was a problem hiding this comment.
The link for the TLS proxy points to servicio-despliegue.md (which corresponds to service-deployment.md). This is incorrect as the TLS proxy is documented in tls-deployment.md. Since these files only exist in English, it should point to ../en/tls-deployment.md.
| [`servicio-despliegue.md`](servicio-despliegue.md)). | |
| ponga un proxy TLS delante (vea [../en/tls-deployment.md](../en/tls-deployment.md)). |
| - [ ] Probar lecturas/escrituras/seeks de índice sobre una **copia** de los datos. | ||
| - [ ] Verificar acentos (salvedad de code page arriba). | ||
| - [ ] Usar Studio (`openads-studio`) en el día a día. | ||
| - [ ] Configurar auto-arranque (asistente, o [`servicio-despliegue.md`](servicio-despliegue.md)). |
There was a problem hiding this comment.
The link to servicio-despliegue.md is broken because the file does not exist in Spanish. It should point to the English version ../en/service-deployment.md.
| - [ ] Configurar auto-arranque (asistente, o [`servicio-despliegue.md`](servicio-despliegue.md)). | |
| - [ ] Configurar auto-arranque (asistente, o [../en/service-deployment.md](../en/service-deployment.md)). |
| Para um build novo, use a import lib do seu compilador em `lib/` (MSVC, MinGW, | ||
| Borland). Binários legados ligados por ordinal: veja | ||
| [`../en/ordinal-compat.md`](../en/ordinal-compat.md). Detalhes de RDD: | ||
| [`rddads-compat.md`](rddads-compat.md). |
There was a problem hiding this comment.
The link to rddads-compat.md is broken because it resolves to docs/pt/rddads-compat.md, which does not exist. It should point to the English version in docs/en/ using a relative path, similar to how ordinal-compat.md is linked.
| [`rddads-compat.md`](rddads-compat.md). | |
| [../en/rddads-compat.md](../en/rddads-compat.md). |
| editar registros, rodar SQL, ver/reconstruir estrutura (reindex, pack, zap) e | ||
| criar/editar objetos do dicionário (tabelas, usuários, índices, regras de RI). | ||
| Proteja com `--http-user usuario:senha`; para exposição pública, ponha um proxy | ||
| TLS na frente (veja [`servico-implantacao.md`](servico-implantacao.md)). |
There was a problem hiding this comment.
The link for the TLS proxy points to servico-implantacao.md (which corresponds to service-deployment.md). This is incorrect as the TLS proxy is documented in tls-deployment.md. Since these files only exist in English, it should point to ../en/tls-deployment.md.
| TLS na frente (veja [`servico-implantacao.md`](servico-implantacao.md)). | |
| TLS na frente (veja [../en/tls-deployment.md](../en/tls-deployment.md)). |
| - [ ] Testar leituras/gravações/seeks de índice numa **cópia** dos dados. | ||
| - [ ] Verificar acentuação (ressalva de code page acima). | ||
| - [ ] Usar o Studio (`openads-studio`) no dia a dia. | ||
| - [ ] Configurar auto-início (wizard, ou [`servico-implantacao.md`](servico-implantacao.md)). |
There was a problem hiding this comment.
The link to servico-implantacao.md is broken because the file does not exist in Portuguese. It should point to the English version ../en/service-deployment.md.
| - [ ] Configurar auto-início (wizard, ou [`servico-implantacao.md`](servico-implantacao.md)). | |
| - [ ] Configurar auto-início (wizard, ou [../en/service-deployment.md](../en/service-deployment.md)). |
1 participant
What & why
Rounds out the adoption story for people coming from ADS on the client side. Today an extracted release is a folder of DLLs + a generic README; this adds the "open the folder and go" experience.
openads-studio.bat/.sh— one-click launcher: starts the engine with the web console and opens the browser. Zero config, and an ephemeral wire port (--port 0) so it never clashes with an Advantage service on 6262. This is the ARC replacement made discoverable.QUICKSTART.md— the three paths in the box: drop-in DLL for a local app, Studio for browsing/editing,openads_serverdfor a network server.docs/{en,pt,es}/migrating-from-ads— a concept-by-concept map (server / Local Server / client DLL / ARC /ads.cfg/ ports) with a checklist, in all three doc languages.Pairs with the server-side
--config(#88) and--setupwizard (#89) PRs, but stands alone — no engine or test changes.Naming
The legacy product is referenced only descriptively (nominative compatibility), with a short trademark / non-affiliation note in each guide. No third-party brand is claimed.
Note for the maintainer
To ship these files inside the release archive, the staging steps in
.github/workflows/release.ymlneed a one-line copy ofQUICKSTART.md+openads-studio.{sh,bat}(andopenads.ini.sampleonce #88 lands). I left CI untouched in this PR — happy to add it if you'd prefer.Validation
Docs + scripts only. The launcher wraps the already-working
openads_serverd --http-portStudio path; the wire/engine is unchanged.