Git-Mirrors/onionshare
1
0
Fork 0
mirror of https://github.com/onionshare/onionshare.git synced 2025-01-12 07:49:39 -05:00
Code Issues Packages Projects Releases Wiki Activity

Update develop docs for 2.3.dev2

Browse Source
This commit is contained in:
Micah Lee 2020-11-10 20:55:21 -08:00
parent 44d608be15
commit 9507f786c5
No known key found for this signature in database
GPG Key ID: 403C2657CD994F73
1 changed files with 88 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

199
docs/source/develop.rst
View File

@ -11,7 +11,7 @@ To use Keybase, download the `Keybase app <https://keybase.io/download>`_, make
OnionShare also has a `mailing list <https://lists.riseup.net/www/subscribe/onionshare-dev>`_ for developers and and designers to discuss the project. OnionShare also has a `mailing list <https://lists.riseup.net/www/subscribe/onionshare-dev>`_ for developers and and designers to discuss the project.
Contributing code Contributing Code
----------------- -----------------
OnionShare source code is to be found in this Git repository: https://github.com/micahflee/onionshare OnionShare source code is to be found in this Git repository: https://github.com/micahflee/onionshare
@ -23,18 +23,13 @@ When you're ready to contribute code, open a pull request in the GitHub reposito
.. _starting_development: .. _starting_development:
Starting development Starting Development
-------------------- --------------------
OnionShare is developed in Python. OnionShare is developed in Python.
To get started, clone the Git repository at https://github.com/micahflee/onionshare/ and then consult the ``BUILD.md`` file. To get started, clone the Git repository at https://github.com/micahflee/onionshare/ and then consult the ``cli/README.md`` file to learn how to set up your development environment for the command-line version, and the ``desktop/README.md`` file to learn how to set up your development environment for the graphical version.
That file contains the necessary technical instructions and commands: Those files contain the necessary technical instructions and commands install dependencies for your platform, and to run OnionShare from the source tree.
* Install dependencies for your platform
* Run OnionShare from the source tree, without building a package
* Building packages
* Making a release of OnionShare
Debugging tips Debugging tips
-------------- --------------
@ -45,70 +40,77 @@ Verbose mode
When developing, it's convenient to run OnionShare from a terminal and add the ``--verbose`` (or ``-v``) flag to the command. When developing, it's convenient to run OnionShare from a terminal and add the ``--verbose`` (or ``-v``) flag to the command.
This prints a lot of helpful messages to the terminal, such as when certain objects are initialized, when events occur (like buttons clicked, settings saved or reloaded), and other debug info. For example:: This prints a lot of helpful messages to the terminal, such as when certain objects are initialized, when events occur (like buttons clicked, settings saved or reloaded), and other debug info. For example::
$ poetry run ./dev_scripts/onionshare -v test.txt $ poetry run onionshare-cli -v ~/Documents/roms/nes/Q-bert\ \(USA\).nes
OnionShare 2.3 | https://onionshare.org/ OnionShare 2.3 | https://onionshare.org/
@@@@@@@@@ @@@@@@@@@
@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@
@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ ___ _ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@ ___ _
@@@@@@ @@@@@@@@@@@@@ / _ \ (_) @@@@@@ @@@@@@@@@@@@@ / _ \ (_)
@@@@ @ @@@@@@@@@@@ | | | |_ __ _ ___ _ __ @@@@ @ @@@@@@@@@@@ | | | |_ __ _ ___ _ __
@@@@@@@@ @@@@@@@@@@ | | | | '_ \| |/ _ \| '_ \ @@@@@@@@ @@@@@@@@@@ | | | | '_ \| |/ _ \| '_ \
@@@@@@@@@@@@ @@@@@@@@@@ \ \_/ / | | | | (_) | | | | @@@@@@@@@@@@ @@@@@@@@@@ \ \_/ / | | | | (_) | | | |
@@@@@@@@@@@@@@@@ @@@@@@@@@ \___/|_| |_|_|\___/|_| |_| @@@@@@@@@@@@@@@@ @@@@@@@@@ \___/|_| |_|_|\___/|_| |_|
@@@@@@@@@ @@@@@@@@@@@@@@@@ _____ _ @@@@@@@@@ @@@@@@@@@@@@@@@@ _____ _
@@@@@@@@@@ @@@@@@@@@@@@ / ___| | @@@@@@@@@@ @@@@@@@@@@@@ / ___| |
@@@@@@@@@@ @@@@@@@@ \ `--.| |__ __ _ _ __ ___ @@@@@@@@@@ @@@@@@@@ \ `--.| |__ __ _ _ __ ___
@@@@@@@@@@@ @ @@@@ `--. \ '_ \ / _` | '__/ _ \ @@@@@@@@@@@ @ @@@@ `--. \ '_ \ / _` | '__/ _ \
@@@@@@@@@@@@@ @@@@@@ /\__/ / | | | (_| | | | __/ @@@@@@@@@@@@@ @@@@@@ /\__/ / | | | (_| | | | __/
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ \____/|_| |_|\__,_|_| \___| @@@@@@@@@@@@@@@@@@@@@@@@@@@@@ \____/|_| |_|\__,_|_| \___|
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@
@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@
@@@@@@@@@ @@@@@@@@@
[Aug 23 2020 22:37:06] Settings.__init__ [Nov 10 2020 20:50:35] Settings.__init__
[Aug 23 2020 22:37:06] Settings.load [Nov 10 2020 20:50:35] Settings.load
[Aug 23 2020 22:37:06] Settings.load: Trying to load /home/user/.config/onionshare/onionshare.json [Nov 10 2020 20:50:35] Common.get_resource_path: filename=wordlist.txt
[Aug 23 2020 22:37:06] ModeSettings.load: creating /home/user/.config/onionshare/persistent/opacity-joining-sappiness.json [Nov 10 2020 20:50:35] Common.get_resource_path: filename=wordlist.txt, path=/home/user/code/onionshare/cli/onionshare_cli/resources/wordlist.txt
[Aug 23 2020 22:37:06] ModeSettings.set: updating opacity-joining-sappiness: general.public = False [Nov 10 2020 20:50:35] ModeSettings.load: creating /home/user/.config/onionshare/persistent/abstain-reprogram-elevate.json
[Aug 23 2020 22:37:06] ModeSettings.set: updating opacity-joining-sappiness: general.autostart_timer = 0 [Nov 10 2020 20:50:35] ModeSettings.set: updating abstain-reprogram-elevate: general.public = False
[Aug 23 2020 22:37:06] ModeSettings.set: updating opacity-joining-sappiness: general.autostop_timer = 0 [Nov 10 2020 20:50:35] ModeSettings.set: updating abstain-reprogram-elevate: general.autostart_timer = 0
[Aug 23 2020 22:37:06] ModeSettings.set: updating opacity-joining-sappiness: general.legacy = False [Nov 10 2020 20:50:35] ModeSettings.set: updating abstain-reprogram-elevate: general.autostop_timer = 0
[Aug 23 2020 22:37:06] ModeSettings.set: updating opacity-joining-sappiness: general.client_auth = False [Nov 10 2020 20:50:35] ModeSettings.set: updating abstain-reprogram-elevate: general.legacy = False
[Aug 23 2020 22:37:06] ModeSettings.set: updating opacity-joining-sappiness: share.autostop_sharing = True [Nov 10 2020 20:50:35] ModeSettings.set: updating abstain-reprogram-elevate: general.client_auth = False
[Aug 23 2020 22:37:06] Web.__init__: is_gui=False, mode=share [Nov 10 2020 20:50:35] ModeSettings.set: updating abstain-reprogram-elevate: share.autostop_sharing = True
[Aug 23 2020 22:37:06] Web.generate_static_url_path: new static_url_path is /static_4kanwd4mt5mcqmpsbptviv3tbq [Nov 10 2020 20:50:35] Web.__init__: is_gui=False, mode=share
[Aug 23 2020 22:37:06] ShareModeWeb.init [Nov 10 2020 20:50:35] Common.get_resource_path: filename=static
[Aug 23 2020 22:37:06] Onion.__init__ [Nov 10 2020 20:50:35] Common.get_resource_path: filename=static, path=/home/user/code/onionshare/cli/onionshare_cli/resources/static
[Aug 23 2020 22:37:06] Onion.connect [Nov 10 2020 20:50:35] Common.get_resource_path: filename=templates
[Aug 23 2020 22:37:06] Settings.__init__ [Nov 10 2020 20:50:35] Common.get_resource_path: filename=templates, path=/home/user/code/onionshare/cli/onionshare_cli/resources/templates
[Aug 23 2020 22:37:06] Settings.load [Nov 10 2020 20:50:35] Web.generate_static_url_path: new static_url_path is /static_qa7rlyxwnfodczrriv3tj5yeoq
[Aug 23 2020 22:37:06] Settings.load: Trying to load /home/user/.config/onionshare/onionshare.json [Nov 10 2020 20:50:35] ShareModeWeb.init
[Aug 23 2020 22:37:06] Onion.connect: tor_data_directory_name=/home/user/.config/onionshare/tmp/tmpig895mfl [Nov 10 2020 20:50:35] Onion.__init__
[Nov 10 2020 20:50:35] Onion.connect
[Nov 10 2020 20:50:35] Settings.__init__
[Nov 10 2020 20:50:35] Settings.load
[Nov 10 2020 20:50:35] Onion.connect: tor_data_directory_name=/home/user/.config/onionshare/tmp/tmpz53ztq3m
[Nov 10 2020 20:50:35] Common.get_resource_path: filename=torrc_template
[Nov 10 2020 20:50:35] Common.get_resource_path: filename=torrc_template, path=/home/user/code/onionshare/cli/onionshare_cli/resources/torrc_template
Connecting to the Tor network: 100% - Done Connecting to the Tor network: 100% - Done
[Aug 23 2020 22:37:14] Onion.connect: Connected to tor 0.4.3.6 [Nov 10 2020 20:50:42] Onion.connect: Connected to tor 0.4.4.5
[Aug 23 2020 22:37:14] Settings.load [Nov 10 2020 20:50:42] Settings.load
[Aug 23 2020 22:37:14] Settings.load: Trying to load /home/user/.config/onionshare/onionshare.json [Nov 10 2020 20:50:42] Web.generate_password: saved_password=None
[Aug 23 2020 22:37:14] Web.generate_password: saved_password=None [Nov 10 2020 20:50:42] Common.get_resource_path: filename=wordlist.txt
[Aug 23 2020 22:37:14] Web.generate_password: built random password: "barrel-unseated" [Nov 10 2020 20:50:42] Common.get_resource_path: filename=wordlist.txt, path=/home/user/code/onionshare/cli/onionshare_cli/resources/wordlist.txt
[Aug 23 2020 22:37:14] OnionShare.__init__ [Nov 10 2020 20:50:42] Web.generate_password: built random password: "pedometer-grower"
[Aug 23 2020 22:37:14] OnionShare.start_onion_service [Nov 10 2020 20:50:42] OnionShare.__init__
[Aug 23 2020 22:37:14] Onion.start_onion_service: port=17605 [Nov 10 2020 20:50:42] OnionShare.start_onion_service
[Aug 23 2020 22:37:14] Onion.start_onion_service: key_type=NEW, key_content=ED25519-V3 [Nov 10 2020 20:50:42] Onion.start_onion_service: port=17610
[Aug 23 2020 22:37:16] ModeSettings.set: updating opacity-joining-sappiness: general.service_id = ttxidvsv4pqzrarvtlojk435vver6wgifrw4pucyzgj2hb3qu6pf6fqd [Nov 10 2020 20:50:42] Onion.start_onion_service: key_type=NEW, key_content=ED25519-V3
[Aug 23 2020 22:37:16] ModeSettings.set: updating opacity-joining-sappiness: onion.private_key = IGzO65Mi9grG7HlLD9ky82O/vWvu3WVByTqCLpZgV0iV2XaSDAqWazNHKkkP18/7jyZZyXwbLo4qOCiYLudlRA== [Nov 10 2020 20:50:46] ModeSettings.set: updating abstain-reprogram-elevate: general.service_id = x5duatuhpiwfzb23iwpjanalvtxdhoj43ria44s53ryy5diywvbu24ad
[Nov 10 2020 20:50:46] ModeSettings.set: updating abstain-reprogram-elevate: onion.private_key = uIXJzY+88tGSAXAjQxdwkzb2L7jHv467RIX1WDieVkFEZjEA7st2p/6uVCM4KM3L9PdShTPScuUv2IEbVQammA==
Compressing files. Compressing files.
[Aug 23 2020 22:37:16] ShareModeWeb.init [Nov 10 2020 20:50:46] ShareModeWeb.init
[Aug 23 2020 22:37:16] ShareModeWeb.set_file_info_custom [Nov 10 2020 20:50:46] ShareModeWeb.set_file_info_custom
[Aug 23 2020 22:37:16] ShareModeWeb.build_zipfile_list [Nov 10 2020 20:50:46] ShareModeWeb.build_zipfile_list
[Aug 23 2020 22:37:16] Web.start: port=17605 [Nov 10 2020 20:50:46] Web.start: port=17610
* Running on http://127.0.0.1:17605/ (Press CTRL+C to quit) * Running on http://127.0.0.1:17610/ (Press CTRL+C to quit)
Give this address to the recipient: Give this address to the recipient:
http://onionshare:barrel-unseated@ttxidvsv4pqzrarvtlojk435vver6wgifrw4pucyzgj2hb3qu6pf6fqd.onion http://onionshare:pedometer-grower@x5duatuhpiwfzb23iwpjanalvtxdhoj43ria44s53ryy5diywvbu24ad.onion
Press Ctrl+C to stop the server Press Ctrl+C to stop the server
@ -118,68 +120,57 @@ You can add your own debug messages by running the ``Common.log`` method from ``
This can be useful when learning the chain of events that occur when using OnionShare, or the value of certain variables before and after they are manipulated. This can be useful when learning the chain of events that occur when using OnionShare, or the value of certain variables before and after they are manipulated.
Local only Local Only
^^^^^^^^^^ ^^^^^^^^^^
Tor is slow, and it's often convenient to skip starting onion services altogether during development. Tor is slow, and it's often convenient to skip starting onion services altogether during development.
You can do this with the ``--local-only`` flag. For example:: You can do this with the ``--local-only`` flag. For example::
$ poetry run ./dev_scripts/onionshare --local-only --receive $ poetry run onionshare-cli --local-only --receive
OnionShare 2.3 | https://onionshare.org/ OnionShare 2.3 | https://onionshare.org/
@@@@@@@@@ @@@@@@@@@
@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@
@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ ___ _ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@ ___ _
@@@@@@ @@@@@@@@@@@@@ / _ \ (_) @@@@@@ @@@@@@@@@@@@@ / _ \ (_)
@@@@ @ @@@@@@@@@@@ | | | |_ __ _ ___ _ __ @@@@ @ @@@@@@@@@@@ | | | |_ __ _ ___ _ __
@@@@@@@@ @@@@@@@@@@ | | | | '_ \| |/ _ \| '_ \ @@@@@@@@ @@@@@@@@@@ | | | | '_ \| |/ _ \| '_ \
@@@@@@@@@@@@ @@@@@@@@@@ \ \_/ / | | | | (_) | | | | @@@@@@@@@@@@ @@@@@@@@@@ \ \_/ / | | | | (_) | | | |
@@@@@@@@@@@@@@@@ @@@@@@@@@ \___/|_| |_|_|\___/|_| |_| @@@@@@@@@@@@@@@@ @@@@@@@@@ \___/|_| |_|_|\___/|_| |_|
@@@@@@@@@ @@@@@@@@@@@@@@@@ _____ _ @@@@@@@@@ @@@@@@@@@@@@@@@@ _____ _
@@@@@@@@@@ @@@@@@@@@@@@ / ___| | @@@@@@@@@@ @@@@@@@@@@@@ / ___| |
@@@@@@@@@@ @@@@@@@@ \ `--.| |__ __ _ _ __ ___ @@@@@@@@@@ @@@@@@@@ \ `--.| |__ __ _ _ __ ___
@@@@@@@@@@@ @ @@@@ `--. \ '_ \ / _` | '__/ _ \ @@@@@@@@@@@ @ @@@@ `--. \ '_ \ / _` | '__/ _ \
@@@@@@@@@@@@@ @@@@@@ /\__/ / | | | (_| | | | __/ @@@@@@@@@@@@@ @@@@@@ /\__/ / | | | (_| | | | __/
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ \____/|_| |_|\__,_|_| \___| @@@@@@@@@@@@@@@@@@@@@@@@@@@@@ \____/|_| |_|\__,_|_| \___|
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@
@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@
@@@@@@@@@ @@@@@@@@@
* Running on http://127.0.0.1:17614/ (Press CTRL+C to quit) * Running on http://127.0.0.1:17635/ (Press CTRL+C to quit)
Files sent to you appear in this folder: /home/user/OnionShare Files sent to you appear in this folder: /home/user/OnionShare
Warning: Receive mode lets people upload files to your computer. Warning: Receive mode lets people upload files to your computer. Some files can potentially take control of your computer if you open them. Only open things from people you trust, or if you know what you are doing.
Some files can potentially take control of your computer if you open them.
Only open things from people you trust, or if you know what you are doing.
Give this address to the sender: Give this address to the sender:
http://onionshare:eject-snack@127.0.0.1:17614 http://onionshare:train-system@127.0.0.1:17635
Press Ctrl+C to stop the server Press Ctrl+C to stop the server
In this case, you load the URL ``http://onionshare:eject-snack@127.0.0.1:17614`` in a normal web-browser like Firefox, instead of using the Tor Browser. In this case, you load the URL ``http://onionshare:train-system@127.0.0.1:17635`` in a normal web-browser like Firefox, instead of using the Tor Browser.
Debugging in Windows Contributing Translations
^^^^^^^^^^^^^^^^^^^^
If you want to obtain debug output from the ``onionshare-gui.exe`` in Windows, edit ``install\pyinstaller.spec`` and change ``console=False`` to ``console=True``.
Then rebuild the EXE with ``install\build_exe.bat`` (you may need to comment out the ``signtool`` commands in the ``build_exe.bat`` and the ``onionshare.nsi`` files, as per the ``BUILD.md`` instructions).
After this, you can run ``onionshare-gui.exe -v`` from a command prompt to see the debug output.
Contributing translations
------------------------- -------------------------
Help make OnionShare easier to use and more familiar and welcoming for people by translating it on `Hosted Weblate <https://hosted.weblate.org/projects/onionshare/>`_. Always keep the "OnionShare" in latin letters, and use "OnionShare (localname)" if needed. Help make OnionShare easier to use and more familiar and welcoming for people by translating it on `Hosted Weblate <https://hosted.weblate.org/projects/onionshare/>`_. Always keep the "OnionShare" in latin letters, and use "OnionShare (localname)" if needed.
To help translate, make a Hosted Weblate account and start contributing. To help translate, make a Hosted Weblate account and start contributing.
Suggestions for original English strings Suggestions for Original English Strings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sometimes the original English strings are wrong, or don't match between the application and the documentation. Sometimes the original English strings are wrong, or don't match between the application and the documentation.
@ -187,23 +178,9 @@ Sometimes the original English strings are wrong, or don't match between the app
File source string improvements by adding @kingu to your Weblate comment, or open a GitHub issue or pull request. File source string improvements by adding @kingu to your Weblate comment, or open a GitHub issue or pull request.
The latter ensures all upstream developers see the suggestion, and can potentially modify the string via the usual code review processes. The latter ensures all upstream developers see the suggestion, and can potentially modify the string via the usual code review processes.
Status of translations Status of Translations
^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^
Here is the current translation status. Here is the current translation status.
If you want start a translation in a language not yet started, please write to the mailing list: onionshare-dev@lists.riseup.net If you want start a translation in a language not yet started, please write to the mailing list: onionshare-dev@lists.riseup.net
.. image:: https://hosted.weblate.org/widgets/onionshare/-/translations/multi-auto.svg .. image:: https://hosted.weblate.org/widgets/onionshare/-/translations/multi-auto.svg
Translate the .desktop file
^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can also translate the ``install/onionshare.desktop`` file.
Duplicate the line that begins with ``Comment=``.
Add the language code to the new line so it becomes ``Comment[lang]=`` (lang should be your language).
You can see what language codes are used for translation by looking at the ``share/locale/*.json`` filenames::
Comment=Original string
Comment[da]=Danish translation of the original string
Do the same for other untranslated lines.