diff --git a/docs/CONTRIBUTING-en-US.md b/docs/CONTRIBUTING-en-US.md index 1b7326b00..079be81e7 100644 --- a/docs/CONTRIBUTING-en-US.md +++ b/docs/CONTRIBUTING-en-US.md @@ -46,14 +46,25 @@ pre-commit install _Attention:_ These steps need to be executed only the first time you interact with the project during the environment setup. After that, just activate the virtual environment (step 3) every time you use or contribute to the repository. ### Windows -The following instructions were tried on Windows 10. -1. [Install Microsoft Visual Build Tools](https://visualstudio.microsoft.com/downloads/). When starting the installation, you need to select `C++ build tools` in the loading tab and also `Windows 10 SDK` and `MSVC v142 - VS 2019 C++ x64/x86 build tools` in the individual components tab. +#### Using Windows terminal +The following instructions were tried on Windows 10 and 11. Remember that if you want to integrate with the [querido-diario-data-processing](https://github.com/okfn-brasil/querido-diario- data-processing) it is preferable that your environment configuration is done [using WSL](CONTRIBUTING.md#using-wsl). + +1. Install [Visual Studio Community](https://visualstudio.microsoft.com/pt-br/downloads/). Before the installation, you need to select in the **Individual Components** tab "Windows 10 SDK" or "11" (depending on your system) and "MSVC v143 build tools - VS 2022 C++ x64/x86 ( v14.32-17.4)". Note that Windows 10 SDK and MSVC v142 - VS 2019 C++ x64/x86 build tools versions will often be updated, so look for similar items under Individual Components to perform the installation (i.e. newer and compatible with your system). Under **Workloads**, select “Desktop development with C++”. Install the updates, close the application and follow the next steps. + 2. Follow all [steps used in Linux](#linux), except for item 3. In it, the command should be: ```console .venv/Scripts/activate.bat ``` _Note_: In Windows commands, the direction of the slash (`/` or `\`) may vary depending on the use of [WSL](https://learn.microsoft.com/en-us/windows/wsl/about). +#### Using WSL + +Open a new Ubuntu terminal and clone the forked [querido-diario](https://github.com/okfn-brasil/querido-diario) repository + +Follow the instructions regarding installation using [Linux](CONTRIBUTING.md#em-linux). + +[This tutorial](https://github.com/Luisa-Coelho/qd-data-processing/blob/readme_update/wsl_windows.md) will help you install and configure WSL on your Windows machine. + ## Automated code formatting Project uses [Black](https://github.com/psf/black) as an automated tool to format and check code style and [isort](https://github.com/pycqa/isort) to sort the imports. CI will fail if your code are not correctly formatted according these tools. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index f85fbd1e7..e91e8d30c 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -46,14 +46,27 @@ pre-commit install _Atenção:_ Estas etapas precisam ser executadas apenas na primeira vez que interagir com o projeto durante a preparação do ambiente. Depois disso, basta ativar o ambiente virtual (passo 3) cada vez que for utilizar ou contribuir com o repositório. ### Em Windows -As instruções a seguir foram experimentadas em Windows 10. -1. [Instale o Microsoft Visual Build Tools](https://visualstudio.microsoft.com/downloads/). Ao iniciar a instalação, você precisa selecionar `C++ build tools` na aba de carregamento e também `Windows 10 SDK` e `MSVC v142 - VS 2019 C++ x64/x86 build tools` na aba de componentes individuais. + +#### Pelo terminal do Windows +As instruções a seguir foram experimentadas em Windows 10 e 11. Lembre-se que caso deseje realizar uma integração com o repositório [querido-diario-data-processing](https://github.com/okfn-brasil/querido-diario-data-processing) é preferível que a sua configuração de ambiente seja feita [utilizando WSL](CONTRIBUTING.md#utilizando-wsl). + +1. Instale o [Visual Studio Comunidade](https://visualstudio.microsoft.com/pt-br/downloads/) . Ao abrir o terminal do instalado do Visual Studio, antes de instalar, você precisa selecionar na aba de **Componentes Individuais** "SDK do Windows 10" ou "11" (a depender do seu sistema) e "Ferramentas de build do MSVC v143 - VS 2022 C++ x64/x86 (v14.32-17.4)". Note que muitas vezes as versões Windows 10 SDK e MSVC v142 - VS 2019 C++ x64/x86 build tools serão atualizadas, portanto procure por itens similares em Componentes individuais para realizar a instalação (ou seja, mais novos e compatíveis com o seu sitema). Em **Cargas de Trabalho**, selecione “Desenvolvimento para desktop com C++”. Instale as atualizações, feche o aplicativo e siga os próximos passos. + 2. Siga todos os [passos usados no Linux](#em-linux), com exceção do item 3. Nele, o comando deve ser: ```console .venv/Scripts/activate.bat ``` _Observação_: Nos comandos em Windows, o sentido da barra (`/` ou `\`) pode variar a depender da utilização de [WSL](https://learn.microsoft.com/pt-br/windows/wsl/about). +#### Utilizando WSL + +Abra um novo terminal do Ubuntu e faça o clone do repositório forked do [querido-diario](https://github.com/okfn-brasil/querido-diario). + +Siga as instruções referentes À instalação utilizando [Linux](CONTRIBUTING.md#em-linux). + +[Este tutorial](https://github.com/Luisa-Coelho/qd-data-processing/blob/readme_update/wsl_windows.md) vai te ajudar na instalação e configuração do WSL na sua máquina Windows. + + ## Formação automática de código O projeto usa [Black](https://github.com/psf/black) como ferramenta de automação para formatar e verificar o estilo do código e usa [isort](https://github.com/pycqa/isort) para organizar as importações. A integração contínua (CI) falhará se seu código não estiver adequadamente formatado. @@ -62,4 +75,4 @@ Mas, se você seguiu as orientações para configurar o ambiente de desenvolvime _Observação_: `make` não é disponibilizado nativamente em Windows, sendo necessário instalá-lo para a utilização sugerida. # Mantendo -As pessoas mantenedoras devem seguir as diretrizes do [Guia para Mantenedoras](https://github.com/okfn-brasil/querido-diario-comunidade/blob/main/.github/CONTRIBUTING.md#mantendo) do Querido Diário. \ No newline at end of file +As pessoas mantenedoras devem seguir as diretrizes do [Guia para Mantenedoras](https://github.com/okfn-brasil/querido-diario-comunidade/blob/main/.github/CONTRIBUTING.md#mantendo) do Querido Diário. diff --git a/docs/README-en-US.md b/docs/README-en-US.md index f9dd77659..2d8ed8766 100644 --- a/docs/README-en-US.md +++ b/docs/README-en-US.md @@ -1,4 +1,4 @@ -**English (US)** | [Português (BR)](/docs/README.md) +**English (US)** | [Português (BR)](/docs/README.md)

Querido Diário @@ -115,4 +115,4 @@ All work produced by OKBR is openly and freely available. # License -Code licensed under the [MIT License](/LICENSE.md). \ No newline at end of file +Code licensed under the [MIT License](/LICENSE.md). diff --git a/docs/README.md b/docs/README.md index 7c64b4ace..ff980dfd6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,4 @@ -**Português (BR)** | [English (US)](/docs/README-en-US.md) +**Português (BR)** | [English (US)](/docs/README-en-US.md)

Querido Diário @@ -133,4 +133,4 @@ Todo o trabalho produzido pela OKBR está disponível livremente. # Licença -Código licenciado sob a [Licença MIT](LICENSE.md). \ No newline at end of file +Código licenciado sob a [Licença MIT](LICENSE.md). diff --git a/docs/TROUBLESHOOTING-en-US.md b/docs/TROUBLESHOOTING-en-US.md index 803cedc2c..0aa8c0a52 100644 --- a/docs/TROUBLESHOOTING-en-US.md +++ b/docs/TROUBLESHOOTING-en-US.md @@ -14,4 +14,28 @@ module.c:1:10: fatal error: Python.h: No such file or directory error: command 'x86_64-linux-gnu-gcc' failed with exit status 1 ``` -Please try to install `python3-dev`. E.g. via `apt install python3-dev`, if you are using a Debian-like distro, or use your distro manager package. Make sure that you use the correct version (e.g. `python3.6-dev` or `python3.7-dev`). You can check your version via `python3 --version`. \ No newline at end of file +Please try to install `python3-dev`. E.g. via `apt install python3-dev`, if you are using a Debian-like distro, or use your distro manager package. Make sure that you use the correct version (e.g. `python3.6-dev` or `python3.7-dev`). You can check your version via `python3 --version`. + +## Error `pinned with ==` + +While running `pip install requeriments`, a inexact pinning error may appear. Therefore, use "--no-deps" along the installation: + +~~~Linux +pip install -r data_collection/requirements-dev.txt --no-deps +~~~ + +## Error `legacy-install` + +In your WSL terminal, a `legacy-install failure`, like this one below, may occur while installing packages. + +``` +error: legacy-install failure +error: command 'x86_64-linux-gnu-gcc' failed: No such file or directory +``` + +Thus, upgrade your pio and install some essential libraries for Linux: + +~~~Linux +python3 -m pip install --upgrade pip +sudo apt-get install build-essential libssl-dev libffi-dev python3-dev +~~~ diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 36e965741..8450b83d3 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -13,4 +13,28 @@ module.c:1:10: fatal error: Python.h: No such file or directory compilation terminated. error: command 'x86_64-linux-gnu-gcc' failed with exit status 1 ``` -Tente instalar `python3-dev`. Por exemplo, via `apt install python3-dev`, se você está usando uma distro Debian, ou utilize o gerenciamento de pacotes da sua distro (por exemplo, `python3.6-dev` or `python3.7-dev`). Você pode saber qual é a sua versão via `python3 --version`. \ No newline at end of file +Tente instalar `python3-dev`. Por exemplo, via `apt install python3-dev`, se você está usando uma distro Debian, ou utilize o gerenciamento de pacotes da sua distro (por exemplo, `python3.6-dev` or `python3.7-dev`). Você pode saber qual é a sua versão via `python3 --version`. + +## Erro `pinned with ==` + +Ao realizar o pip install requeriments pode ocorrer um erro de fixação inexata, então utilize o "--no-deps" ao instalar: + +~~~Linux +pip install -r data_collection/requirements-dev.txt --no-deps +~~~ + +## Erro `legacy-install` + +Ao instalar bibliotecas pode ocorrer o seguinte erro no seu terminal WSL: + +``` +error: legacy-install failure +error: command 'x86_64-linux-gnu-gcc' failed: No such file or directory +``` + +Então faça o upgrade do pip e instale algumas bibliotecas essenciais do Linux: + +~~~Linux +python3 -m pip install --upgrade pip +sudo apt-get install build-essential libssl-dev libffi-dev python3-dev +~~~