You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/cli.rst
+60-1Lines changed: 60 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -71,6 +71,47 @@ You can run Basilisp code from a string or by directly naming a file with the CL
71
71
72
72
basilisp run path/to/some/file.lpy
73
73
74
+
Any arguments passed to ``basilisp run`` beyond the name of the file or the code string will be bound to the var :lpy:var:`*command-line-args*` as a vector of strings.
75
+
If no arguments are provided, ``*command-line-args*`` will be ``nil``.
76
+
77
+
.. code-block:: bash
78
+
79
+
$ basilisp run -c '(println *command-line-args*)' 1 2 3
80
+
[1 2 3]
81
+
$ basilisp run -c '(println *command-line-args*)'
82
+
nil
83
+
84
+
.. _run_basilisp_applications:
85
+
86
+
Run Basilisp as an Application
87
+
------------------------------
88
+
89
+
Python applications don't have nearly as many constraints on their entrypoints as do Java applications.
90
+
Nevertheless, developers may have a clear entrypoint in mind when designing their application code.
91
+
In such cases, it may be desirable to take advantage of the computed Python ``sys.path`` to invoke your entrypoint.
92
+
To do so, you can use the ``basilisp run -n`` flag to invoke an namespace directly:
93
+
94
+
.. code-block:: bash
95
+
96
+
basilisp run -n package.core
97
+
98
+
When invoking your Basilisp code via namespace name, the specified namespace name will be bound to the var :lpy:var:`*main-ns*` as a symbol.
99
+
This allows you to gate code which should only be executed when this namespace is executed as an entrypoint, but would otherwise allow you to ``require`` the namespace normally.
100
+
101
+
.. code-block:: clojure
102
+
103
+
(when (= *main-ns* 'package.core)
104
+
(start-app))
105
+
106
+
This approximates the Python idiom of gating execution on import using ``if __name__ == "__main__":``.
107
+
108
+
This variant of ``basilisp run`` also permits users to provide command line arguments bound to :lpy:var:`*command-line-args*` as described above.
109
+
110
+
.. note::
111
+
112
+
Only ``basilisp run -n`` binds the value of :lpy:var:`*main-ns*`.
113
+
In all other cases, it will be ``nil``.
114
+
74
115
.. _run_basilisp_tests:
75
116
76
117
Run Basilisp Tests
@@ -82,4 +123,22 @@ If you installed the `PyTest <https://docs.pytest.org/en/7.0.x/>`_ extra, you ca
82
123
83
124
basilisp test
84
125
85
-
Because Basilisp defers all testing logic to PyTest, you can use any standard PyTest arguments and flags from this entrypoint.
126
+
Because Basilisp defers all testing logic to PyTest, you can use any standard PyTest arguments and flags from this entrypoint.
127
+
128
+
.. _bootstrap_cli_command:
129
+
130
+
Bootstrap Python Installation
131
+
-----------------------------
132
+
133
+
For some installations, it may be desirable to have Basilisp readily importable whenever the Python interpreter is started.
134
+
You can enable that as described in :ref:`bootstrapping`:
135
+
136
+
.. code-block:: bash
137
+
138
+
basilisp bootstrap
139
+
140
+
If you would like to remove the bootstrapped Basilisp from your installation, you can remove it:
Copy file name to clipboardExpand all lines: docs/gettingstarted.rst
+36-1Lines changed: 36 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -132,4 +132,39 @@ For systems where the shebang line allows arguments, you can use ``#!/usr/bin/en
132
132
.. code-block:: clojure
133
133
134
134
#!/usr/bin/env basilisp-run
135
-
(println "Hello world!")
135
+
(println "Hello world!")
136
+
137
+
Finally, Basilisp has a command line option to bootstrap your Python installation such that Basilisp will already be importable whenever Python is started.
138
+
This takes advantage of the ``.pth`` file feature supported by the `site <https://docs.python.org/3/library/site.html>`_ package.
139
+
Specifically, any file with a ``.pth`` extension located in any of the known ``site-packages`` directories will be read at startup and, if any line of such a file starts with ``import``, it is executed.
140
+
141
+
.. code-block:: bash
142
+
143
+
$ basilisp bootstrap
144
+
Your Python installation has been bootstrapped! You can undo this at any time with with `basilisp bootstrap --uninstall`.
145
+
$ python
146
+
Python 3.12.1 (main, Jan 3 2024, 10:01:43) [GCC 11.4.0] on linux
147
+
Type "help", "copyright", "credits" or "license"for more information.
This method also enables you to directly execute Basilisp scripts as Python modules using ``python -m {namespace}``.
152
+
Basilisp namespaces run as a Python module directly via ``python -m`` are resolved within the context of the current ``sys.path`` of the active Python interpreter.
153
+
154
+
.. code-block:: bash
155
+
156
+
basilisp bootstrap # if you haven't already done so
Most modern Python packaging tools do not permit arbitrary code to be installed during package installation, so this step must be performed manually.
163
+
It only needs to be run once per Python installation or virtualenv.
164
+
165
+
.. warning::
166
+
167
+
Code in ``.pth`` files is executed each time the Python interpreter is started.
168
+
The Python ``site`` documentation warns that "[i]ts impact should thus be kept to a minimum".
169
+
Bootstrapping Basilisp can take as long as 30 seconds (or perhaps longer, though typically much shorter on modern systems) on the first run due to needing to compile :lpy:ns:`basilisp.core` to Python bytecode.
170
+
Subsequent startups should be considerable faster unless users have taken any measures to disable :ref:`namespace_caching`.
0 commit comments