NVDA (NonVisual Desktop Access) jest darmowym, otwartym czytnikiem ekranu dla Microsoft Windows.Jest rozwijany przez NV Access we współpracy z globalną społecznością współpracowników.Aby dowiedzieć się więcej o NVDA lub pobrać kopię, odwiedź główną stronę NV Access.

Uwaga: projekt NVDA posiada Citizen and Contributor Code of Conduct. NV Access oczekuje, że wszyscy współpracownicy i inni członkowie społeczności przeczytają i będą przestrzegać zasad określonych w tym dokumencie podczas uczestniczenia lub wnoszenia wkładu do tego projektu.

Uzyskaj wsparcie

Jeśli jesteś początkującym, zaawansowanym użytkownikiem, nowym lub długoletnim deweloperem, lub jeśli jesteś organizacją chcącą dowiedzieć się więcej lub wnieść wkład do NVDA, możesz uzyskać wsparcie poprzez istniejącą dokumentację, jak również kilka kanałów komunikacyjnych dedykowanych dla czytnika ekranu NVDA. Poniżej znajduje się przegląd najważniejszych źródeł wsparcia.

Documentation

• NVDA User Guide
• NVDA Developer Guide
• NVDA Add-ons Development Internals
• NVDA ControllerClient manual
• Dalsza dokumentacja jest zawarta w Wiki tego repozytorium oraz w Community Wiki

Kanały komunikacyjne

• NVDA Users Mailing List
• NVDA Developers Mailing List
• NVDA Add-ons Mailing List
• Instant Messaging channel for NVDA Support
• Inne źródła, w tym grupy i profile na kanałach mediów społecznościowych, specyficzne dla danego języka strony internetowe i listy mailingowe itp.

Możesz również uzyskać bezpośrednie wsparcie od NV Access. Zobacz stronę NV Access po więcej szczegółów.

Inne kluczowe linki projektu

• NVDA na GitHub
• Problemy NVDA na GitHub: Raporty o błędach, prośby o funkcje, itp.
• Migawki rozwojowe NVDA: Automatycznie generowane kompilacje projektu w jego aktualnym stanie rozwoju
• NVDA add-ons: Pobierz dodatki do rozszerzenia NVDA
• NVDA Add-ons coordination and support center: wszystko o środowisku dodatków NVDA
• NVDA Add-ons Template: Repozytorium do generowania szablonu Add-ons
• Tłumaczenie NVDA: Informacje o tym, jak przetłumaczyć NVDA na inny język
• NVDA Controller Client (2010-02-19): NVDA API dla zewnętrznych aplikacji do bezpośredniego mówienia lub brajlowskich wiadomości, itp.
• Contributing to NVDA: Wytyczne dotyczące współtworzenia kodu źródłowego NVDA
• Lista e-mailowa NVDA commits: Powiadomienia o wszystkich commitach do repozytorium Git
• Stare archiwa e-mail: zawierają dyskusje na temat rozwoju NVDA

Pobieranie kodu źródłowego

Projekt NVDA używa systemu kontroli wersji Git dla swojego kodu źródłowego i dokumentacji.

Repozytorium Git NVDA znajduje się pod adresem https://github.com/nvaccess/nvda.git. Można je sklonować za pomocą następującego polecenia, które umieści pliki w katalogu o nazwie nvda:

git clone --recursive https://github.com/nvaccess/nvda.git

Opcja --recursive jest potrzebna do pobrania różnych podmodułów Git, których używamy.

Zależności

Źródło NVDA zależy od kilku innych pakietów, aby działać poprawnie.

Zainstalowane zależności

Następujące zależności muszą być zainstalowane w twoim systemie:

• Python, wersja 3.8, 32 bit
  • Użyj najnowszej wersji minor, jeśli to możliwe.
• Microsoft Visual Studio 2019 Community, wersja 16.3 lub nowsza:
  • Pobierz z https://visualstudio.microsoft.com/vs/
  • Podczas instalacji Visual Studio należy włączyć następujące elementy:
    • Na karcie Obciążenia robocze
      • w grupie Windows:
        • Desktop development with C++
      • Następnie w sekcji Szczegóły instalacji, w sekcji Desktop for C++, grupowanie Opcjonalne, upewnij się, że wybrane są następujące elementy:
        • MSVC v142 – VS 2019 C++ x64/x86 build tools
        • Windows 10 SDK (10.0.19041.0)
        • C++ ATL for v142 build tools (x86 & x64)
        • C++ Clang tools for Windows
    • Na karcie Poszczególne komponenty upewnij się, że zaznaczone są następujące elementy:
      • MSVC v142 – VS 2019 C++ ARM64 build tools
      • C++ ATL for v142 build tools (ARM64)

Git Submodules

Niektóre zależności są zawarte w submodułach Git.Jeśli nie przekazałeś opcji --recursive do git clone, będziesz musiał uruchomić git submodule update --init.Za każdym razem, gdy wymagany submoduł się zmienia (np. po git pull), będziesz musiał uruchomić git submodule update.Jeśli nie jesteś pewien, uruchom git submodule update po każdym git pull, merge lub checkout.

Dla odniesienia, następujące zależności runtime są zawarte w submodułach Git:

• eSpeak NG, wersja 1.51-dev commit 53915bf0a
• Sonic, commit 4f8c1d11
• IAccessible2, commit cbc1f29631780
• liblouis, wersja 3.17.0
• Unicode Common Locale Data Repository (CLDR), wersja 38.1
• NVDA obrazy i dźwięki
• Adobe Acrobat accessibility interface, wersja XI
• MinHook, oznaczona wersja 1.2.2
• brlapi Python bindings, wersja 0.8 lub późniejsza, dystrybuowana z BRLTTY for Windows, wersja 6.1
• lilli.dll, wersja 2.1.0.0
• Pythonowy interfejs do sterownika/układu FTDI
• Java Access Bridge 32 bit, z Zulu Community OpenJDK build 13.0.1+10Zulu (13.28.11)

Dodatkowo, następujące zależności czasu kompilacji są zawarte w podmodule git miscDeps:

• txt2tags, wersja 2.5
• Nulsoft Install System, wersja 2.51
• NSIS UAC plug-in, wersja 0.2.4, ansi
• xgettext i msgfmt z GNU gettext
• Boost Optional (stand-alone header), z commit 3922965

Następujące zależności nie są potrzebne większości ludzi i nie są zawarte w submodułach Git:

• Do generowania dokumentacji deweloperskiej dla nvdaHelper: Doxygen Windows installer, wersja 1.8.15:

• Gdy używasz Visual Studio Code jako preferowanego zintegrowanego środowiska programistycznego, możesz skorzystać z naszej wstępnie przygotowanej konfiguracji przestrzeni roboczej dla Visual Studio Code.Chociaż projekt VSCode nie jest dołączony jako submoduł do repozytorium NVDA, możesz łatwo sprawdzić konfigurację obszaru roboczego w swoim repozytorium, wykonując poniższe polecenia z katalogu głównego repozytorium.

  git clone https://github.com/nvaccess/vscode-nvda.git .vscode

Zależności Pythona

NVDA i jej system kompilacji zależą również od obszernej listy pakietów Pythona. Wszystkie one są wymienione wraz z ich konkretnymi wersjami w pliku requirements.txt w katalogu głównym tego repozytorium. Pakiety te zostaną zainstalowane w izolowanym wirtualnym środowisku Pythona w tym repozytorium i nie będą miały wpływu na ogólnosystemowy zestaw pakietów.

Przygotowanie drzewa źródłowego

Zanim będzie można uruchomić kod źródłowy NVDA, należy przygotować drzewo źródłowe. W tym celu należy otworzyć wiersz poleceń, przejść do katalogu głównego dystrybucji źródeł NVDA i wpisać:

scons source

Powinno się to powtórzyć za każdym razem, gdy zmieni się wersja comtypes lub zostaną dodane lub zmienione pliki językowe.Zauważ, że jeśli chcesz uzyskać dostęp do dokumentacji użytkownika z menu pomocy podczas uruchamiania wersji źródłowej, będziesz musiał również dodać user_docs do wiersza poleceń w następujący sposób:

scons source user_docs

Podczas zwykłego testowania lub zatwierdzania zmian, może być szybciej po prostu wykonując scons source, ponieważ dokumentacja użytkownika zmieni się za każdym razem, gdy zmieni się numer rewizji.

Kompilowanie NVDAHelper z opcjami debugowania

Pomiędzy innymi, przygotowanie drzewa źródłowego buduje biblioteki NVDAHelper.Jeśli próbujesz debugować nvdaHelper, możesz kontrolować różne opcje debugowania przez budowanie ze zmiennymi wiersza poleceń nvdaHelperDebugFlags i nvdaHelperLogLevel.

Zmienna nvdaHelperLogLevel określa poziom logowania (0-59), który chcesz zobaczyć, niższy jest bardziej dosłowny. Domyślnie jest to 15.

Zmienna nvdaHelperDebugFlags przyjmuje jedną lub więcej z następujących flag:

• debugCRT: biblioteki zostaną połączone z debugowanym runtime C, a asercje zostaną włączone. (Domyślnie używany jest normalny CRT, a asercje są wyłączone.)
• RTC: będą włączone kontrole runtime (uszkodzenie stosu, niezainicjowane zmienne, itp.). (Domyślnie brak kontroli runtime.)
• analyze: uruchamia analizę kodu MSVC na całym kodzie nvdaHelpera, zatrzymując się na każdym ostrzeżeniu. (domyślnie brak analizy).

Słowa specjalne none i all mogą być również użyte zamiast poszczególnych flag.

Następuje przykład, który włącza debugowanie CRT i sprawdzanie typu run

scons source nvdaHelperDebugFlags=debugCRT,RTC

Pliki pdb symboli są zawsze tworzone podczas budowania, niezależnie od flag debugowania.Nie są one jednak dołączane do dystrybucji NVDA.Zamiast tego scons symbolsArchive zapakuje je jako oddzielne archiwum.

Domyślnie, kompilacje nie używają także żadnych optymalizacji kompilatora.Proszę zobaczyć argument słowa kluczowego release, aby dowiedzieć się, jakie optymalizacje kompilatora zostaną włączone.

Uruchamianie kodu źródłowego

Możliwe jest uruchomienie NVDA bezpośrednio ze źródła bez konieczności budowania pełnego pakietu binarnego i launchera.Aby uruchomić NVDA ze źródła, używając cmd.exe, wykonaj runnvda.bat w korzeniu repozytorium.

Aby wyświetlić pomoc dotyczącą argumentów, które NVDA zaakceptuje, użyj opcji -h lub --help.Argumenty te są również udokumentowane w podręczniku użytkownika.

Budowanie NVDA

Binarna kompilacja NVDA może być uruchomiona na systemie bez zainstalowanego Pythona i wszystkich innych zależności NVDA (tak jak to robimy dla snapshotów i wydań).

Archiwa binarne i pakiety mogą być tworzone przy użyciu scons z korzenia dystrybucji źródła NVDA. Aby zbudować dowolny z poniższych elementów, należy otworzyć wiersz poleceń i przejść do tego katalogu.

Aby stworzyć niezarchiwizowany plik binarny (odpowiednik rozpakowanego archiwum przenośnego), należy wpisać:

scons dist

Kompilacja zostanie utworzona w katalogu dist.

Budowanie instalatora

Aby utworzyć archiwum launchera (jeden plik wykonywalny umożliwiający instalację lub wygenerowanie przenośnego dist), wpisz:

scons launcher

Archiwum zostanie umieszczone w katalogu wyjściowym.

Tworzenie dokumentacji deweloperskiej

Aby wygenerować przewodnik dewelopera NVDA, wpisz:

scons developerGuide

Przewodnik dewelopera zostanie umieszczony w folderze devDocs w katalogu wyjściowym.

Aby wygenerować dokumentację kodu źródłowego opartą na HTML, wpisz:

scons devDocs

Dokumentacja zostanie umieszczona w folderze NVDA w katalogu wyjściowym.

Aby wygenerować dokumentację deweloperską dla nvdaHelper (nie zawartą w celu devDocs):

scons devDocs_nvdaHelper

Dokumentacja zostanie umieszczona w folderze devDocs\nvdaHelper w katalogu wyjściowym.

Generowanie archiwum symboli debugowania

Aby wygenerować archiwum symboli debugowania dla różnych binariów dll/exe, wpisz:

scons symbolsArchive

Archiwum zostanie umieszczone w katalogu wyjściowym.

Wygeneruj szablon tłumaczenia

Aby wygenerować szablon tłumaczenia gettext (dla tłumaczy), wpisz:

scons pot

Dostosowywanie kompilacji

Opcjonalnie, kompilacja może być dostosowana przez podanie zmiennych w wierszu poleceń:

• version: Wersja tej kompilacji.
• release: Czy jest to wersja release.
  • Umożliwia to różne optymalizacje kompilatora C++, takie jak /O2 i optymalizacja całego programu.
  • Instruuje także Pythona, aby generował zoptymalizowany kod bajtowy.
• publisher: Wydawca tej kompilacji.
• certFile: Plik certyfikatu, za pomocą którego należy podpisać pliki wykonywalne. Certyfikat musi być w formacie pfx i zawierać klucz prywatny.
• certPassword: Hasło do klucza prywatnego w certyfikacie podpisującym. Jeśli zostanie pominięte, hasło nie zostanie przyjęte.
• certTimestampServer: Adres URL serwera timestampingu, który ma być używany do timestampingu podpisów authenticode. Jeśli zostanie pominięty, podpisy nie będą znakowane czasem.
• outputDir: Katalog, w którym zostaną umieszczone ostatecznie zbudowane archiwa i inne.
• targetArchitectures: Architektury docelowe, które NVDA powinna obsługiwać. Możliwe wartości to all, x86 i x86_64. To powinno być pozostawione jako domyślne.

Na przykład, aby zbudować launcher z konkretną wersją, możesz wpisać:

scons launcher version=test1

Więcej zobacz plik sconstruct.

Uruchamianie testów automatycznych

Jeśli dokonasz zmian w kodzie NVDA, powinieneś uruchomić testy automatyczne NVDA.Testy te pomagają upewnić się, że zmiany w kodzie nie spowodują niezamierzonego przerwania funkcjonalności, która wcześniej działała.

Aby uruchomić testy (testy jednostkowe, sprawdzanie ciągów znaków), najpierw zmień katalog na główny w dystrybucji źródeł NVDA, jak powyżej.Następnie uruchom:

scons tests

Testy jednostkowe

Aby uruchomić tylko określone testy jednostkowe, określ je za pomocą zmiennej unitTests w wierszu poleceń.Testy powinny być podane jako lista rozdzielona przecinkami.Każdy test powinien być określony jako moduł Pythona, klasa lub metoda względem katalogu tests\unit.Na przykład, aby uruchomić tylko metody klas TestMove i TestSelection w pliku tests\unit\test_cursorManager.py, wykonaj to polecenie:

scons tests unitTests=test_cursorManager.TestMove,test_cursorManager.TestSelection

Sprawdzanie ciągów translatowalnych

Aby uruchomić tylko sprawdzanie ciągów translatowalnych (które sprawdza, czy wszystkie ciągi translatowalne mają komentarze tłumacza), wykonaj:

scons checkPot

Linting twoich zmian

Aby upewnić się, że twoje zmiany są zgodne ze stylem kodowania NVDA, możesz uruchomić lokalnie linter Flake8.Niektórzy programiści zauważyli, że pewne komunikaty o błędach lincingu są mylące, zostały one wyjaśnione w tests/lint/readme.md.runlint.bat użyje Flake8 do sprawdzenia tylko różnic pomiędzy Twoim katalogiem roboczym a określoną gałęzią base.Jeśli tworzysz Pull Request, gałąź base, której tutaj używasz powinna być taka sama jak docelowa, której użyłbyś dla Pull Request. W większości przypadków będzie to origin/master.

runlint origin/master

Aby szybciej otrzymywać ostrzeżenia o błędach lintingu, możesz chcieć zintegrować Flake8 z innymi narzędziami programistycznymi, których używasz.Więcej szczegółów znajdziesz w tests/lint/readme.md

Testy jednostkowe

Testy jednostkowe można uruchamiać za pomocą skryptu rununittests.bat.Wewnętrznie skrypt ten używa Pythonowego frameworka testowego Nose do wykonywania testów.Wszelkie argumenty podane do rununittests.bat są przekazywane do Nose.Proszę odnieść się do własnej dokumentacji Nose, jak filtrować testy itp.

Testy systemowe

Testy systemowe mogą być uruchamiane za pomocą skryptu runsystemtests.bat.Wewnętrznie ten skrypt używa frameworka testowego Robot do wykonywania testów.Wszelkie argumenty podane do runsystemtests.bat są przekazywane do Robot.Więcej szczegółów (w tym filtrowanie i wykluczanie testów) zobacz tests/system/readme.md.

Wnoszenie wkładu do NVDA

Jeśli chciałbyś wnieść swój kod lub dokumentację do NVDA, możesz przeczytać więcej informacji w naszym przewodniku wnoszenia wkładu.