Download as
Browse Code »

Commit 2276957fd7e662bd5394b0d395497f59e8973726

Authored by Carlos Picanco
1 parent 04b15d5b
Exists in master

update docs - add pt-br install instructions 

- need to update en install instructions
Showing 3 changed files with 250 additions and 52 deletions   Show diff stats
... ... @@ -1,52 +0,0 @@
1   -/*
2   - Free-mtrix - Free cultural selection and social behavior experiments.
3   - Copyright (C) 2016-2017 Carlos Rafael Fernandes Picanço, Universidade Federal do Pará.
4   -
5   - The present file is distributed under the terms of the GNU General Public License (GPL v3.0).
6   -
7   - You should have received a copy of the GNU General Public License
8   - along with this program. If not, see <http://www.gnu.org/licenses/>.
9   -*/
10   -
11   -## How to install?
12   -
13   -### Linux
14   -
15   - 1. Install libzmq.so (see http://zeromq.org/intro:get-the-software), v3.2.5, 64 or 32 bits, on your system.
16   -
17   - 2. Done!
18   -
19   -### Windows
20   -
21   - 1. Download and install Visual C++ Redistributable for Visual Studio 2015. You may find it here: https://www.microsoft.com/en-us/download/details.aspx?id=48145
22   -
23   - 2. Copy the `libzmq.dll` (v3.2.5, 32bits, dynamic, compiled with VS 2015) library to the same folder as the `cultural_matrix.exe` file.
24   -
25   - 3. Done!
26   -
27   -## How to setup?
28   -
29   - - You have at least two options.
30   - 1. Running from different folders in one machine (default for debugging).
31   - 2. Running from different machines in a local network.
32   -
33   - - If you have a firewall enabled, you must create a firewall rule adding the program as an exception.
34   -
35   - - You will need an instance of the program running as Server (researcher) and others running as Clients (players). You will need at least two clients.
36   -
37   - - Clients must connect to the IP address of the Server; just create a file named 'IP' in the root folder of each client containing the Server IP on the first line.
38   -
39   -## How to compile?
40   -
41   - 1. Install Lazarus RAD IDE (v1.6.2+) Free Pascal compiler and sources (v3.0.0+): http://lazarus-ide.org/.
42   - 2. Compile and install libzmq (v3.2.5) on your system: http://zeromq.org/intro:get-the-software.
43   - 3. Install epiktimer
44   -
45   - Note: If windows, all sofware must be compiled for 32bits, otherwise, you must write 64bits support yourself.
46   -
47   -## Known Issues
48   -
49   -**`A referral was returned from the server`**
50   -
51   - - Windows Only Error.
52   - - Solution 1: Right click at the `.exe` and select properties. In the tab compatibility, check the checkbox "Run as administrator".
53 0 \ No newline at end of file
docs/INSTALL/manual_en.md 0 → 100644
  Diff comments   View file @2276957
... ... @@ -0,0 +1,54 @@
  1 +/*
  2 + Free-mtrix - Free cultural selection and social behavior experiments.
  3 + Copyright (C) 2016-2017 Carlos Rafael Fernandes Picanço, Universidade Federal do Pará.
  4 +
  5 + The present file is distributed under the terms of the GNU General Public License (GPL v3.0).
  6 +
  7 + You should have received a copy of the GNU General Public License
  8 + along with this program. If not, see <http://www.gnu.org/licenses/>.
  9 +*/
  10 +
  11 +# Manual
  12 +
  13 +## How to install?
  14 +
  15 +### Linux
  16 +
  17 + 1. Install libzmq.so (see http://zeromq.org/intro:get-the-software), v3.2.5, 64 or 32 bits, on your system.
  18 +
  19 + 2. Done!
  20 +
  21 +### Windows
  22 +
  23 + 1. Download and install Visual C++ Redistributable for Visual Studio 2015. You may find it here: https://www.microsoft.com/en-us/download/details.aspx?id=48145
  24 +
  25 + 2. Copy the `libzmq.dll` (v3.2.5, 32bits, dynamic, compiled with VS 2015) library to the same folder as the `cultural_matrix.exe` file.
  26 +
  27 + 3. Done!
  28 +
  29 +## How to setup?
  30 +
  31 + - You have at least two options.
  32 + 1. Running from different folders in one machine (default for debugging).
  33 + 2. Running from different machines in a local network.
  34 +
  35 + - If you have a firewall enabled, you must create a firewall rule adding the program as an exception.
  36 +
  37 + - You will need an instance of the program running as Server (researcher) and others running as Clients (players). You will need at least two clients.
  38 +
  39 + - Clients must connect to the IP address of the Server; just create a file named 'IP' in the root folder of each client containing the Server IP on the first line.
  40 +
  41 +## How to compile?
  42 +
  43 + 1. Install Lazarus RAD IDE (v1.6.2+) Free Pascal compiler and sources (v3.0.0+): http://lazarus-ide.org/.
  44 + 2. Compile and install libzmq (v3.2.5) on your system: http://zeromq.org/intro:get-the-software.
  45 + 3. Install epiktimer
  46 +
  47 + Note: If windows, all sofware must be compiled for 32bits, otherwise, you must write 64bits support yourself.
  48 +
  49 +## Known Issues
  50 +
  51 +**`A referral was returned from the server`**
  52 +
  53 + - Windows Only Error.
  54 + - Solution 1: Right click at the `.exe` and select properties. In the tab compatibility, check the checkbox "Run as administrator".
0 55 \ No newline at end of file
... ...
docs/INSTALL/manual_pt_br.md 0 → 100644
  Diff comments   View file @2276957
... ... @@ -0,0 +1,196 @@
  1 +/*
  2 + Free-mtrix - Free cultural selection and social behavior experiments.
  3 + Copyright (C) 2016-2017 Carlos Rafael Fernandes Picanço, Universidade Federal do Pará.
  4 +
  5 + The present file is distributed under the terms of the GNU General Public License (GPL v3.0).
  6 +
  7 + You should have received a copy of the GNU General Public License
  8 + along with this program. If not, see <http://www.gnu.org/licenses/>.
  9 +*/
  10 +
  11 +# Manual
  12 +
  13 +## Sumário.
  14 +
  15 + 1 - Introdução.
  16 +
  17 + 2 - Designer.
  18 +
  19 + 2.1 - Instalação.
  20 + 2.2 - Compilação.
  21 + 2.3 - Execução.
  22 + 2.3.1 - Windows.
  23 + 2.3.2 - Sistemas Operacionais Linux.
  24 + 2.4 - Utilização.
  25 +
  26 + 3 - Runner.
  27 +
  28 + 3.1 - Instalação.
  29 + 3.1.1 - libzmq no Windows.
  30 + 3.1.2 - libzmq em Sistemas Operacionais Linux.
  31 + 3.2 - Compilação.
  32 + 3.1.1 - Windows.
  33 + 3.1.2 - Sistemas Operacionais Linux.
  34 + 3.3 - Execução.
  35 + 3.3.1 - Windows.
  36 + 3.3.2 - Sistemas Operacionais Linux.
  37 + 3.3.3 - Observações para todos os sistemas.
  38 + 3.4 - Utilização.
  39 + 3.4.1 - Em um único computador.
  40 + 3.4.2 - Em uma rede local.
  41 + 4 - Problemas conhecidos e soluções.
  42 + 4.1 - Uma referência foi retornada do servidor.
  43 +
  44 + 5 - Referências.
  45 +
  46 +## 1. Introdução
  47 +
  48 + Free-mtrix (v1.0.0) é um sistema que permite o planejamento e a apresentação de experimentos sociais baseados em tarefas similares àquelas apresentadas por Vich, Andery e Glenn (2009). Ele é composto por dois programas de computador. O programa `Designer` é usado para o planejamento e o programa `Runner` para a apresentação de experimentos.
  49 +
  50 +## 2. Designer
  51 +
  52 +### 2.1. Instalação
  53 +
  54 + O programa `Designer` é uma aplicação portável (portable application) e não necessita de instalação.
  55 +
  56 +### 2.2. Compilação
  57 +
  58 + Para compilar o programa `Designer` siga os passos a seguir:
  59 +
  60 + 1. Obtenha uma cópia do código fonte: https://github.com/lacs-ufpa/free-mtrix.git.
  61 + 2. Instale o Lazarus (Interface de Desenvolvimento Rápido de Aplicações) versão 1.6.2 ou superior.
  62 + 3. Execute o Lazarus.
  63 + 4. Abra o arquivo `experiment_designer.lpi` localizado na pasta `experiment_designer` por meio da interface gráfica do Lazarus.
  64 + 5. Execute o comando `compilar` do Lazarus (por exemplo, apertando F9).
  65 +
  66 +### 2.3. Execução
  67 +
  68 +#### 2.3.1. Windows
  69 +
  70 + Nos sistemas operacionais Windows, o programa `Designer` é executado por meio do arquivo `experiment_designer.exe`, localizado na pasta `experiment_designer`. Recomenda-se a execução no Windows 10, 32 bits.
  71 +
  72 +#### 2.3.2. Sistemas Operacionais Linux
  73 +
  74 + Nos sistemas operacionais Linux, o programa `Designer` é executado por meio do arquivo `experiment_designer`, localizado na pasta `experiment_designer`. Recomenda-se a execução no Debian 8, 32 ou 64 bits.
  75 +
  76 +### 2.4. Utilização
  77 +
  78 + O programa `Designer` é usado para o planejamento de experimentos sociais por meio do preenchimento de um formulário pelo pesquisador. O formulário é curto (~10 min) e utiliza a terminologia do campo de estudos chamado "Análise do Comportamento", tornando-o intuitivo aos pesquisadores da área. Todo o processo de preenchimento é salvo automaticamente. Ao final, um arquivo de configuração do experimento é disponibilizado para uso, reuso, arquivamento ou edição.
  79 +
  80 +## 3. Runner
  81 +
  82 +### 3.1 Instalação
  83 +
  84 + O programa `Runner` é uma aplicação auto-executável e não necessita de instalação. Entretanto, o programa `Runner` depende da instalação da biblioteca `libzmq` (http://zeromq.org/). Uma cópia da biblioteca libzmq é distribuida com o Free-mtrix. Confira a seguir como instalar a biblioteca no seu sistema.
  85 +
  86 +#### 3.1.1. libzmq no Windows
  87 +
  88 +Siga os passos a seguir para instalar a biblioteca libzmq no Windows 10.
  89 +
  90 + 1. Baixe e instale o `Visual C++ Redistributable for Visual Studio 2015`. Você pode encontrá-lo aqui: https://www.microsoft.com/en-us/download/details.aspx?id=48145
  91 + 2. Copie o arquivo `libzmq.dll` distribuido com este (v3.2.5, 32bits, dinâmica, compilada com o VS 2015).
  92 + - Alternativamente, você mesmo pode construir a biblioteca seguindo as instruções aqui: http://zeromq.org/intro:get-the-software#toc8.
  93 + 3. Cole o arquivo `libzmq.dll` dentro da pasta `experiment_runner`. A pasta deve conter o arquivo executável `experiment_runner.exe`.
  94 + 4. Pronto!
  95 +
  96 +#### 3.1.2. libzmq em Sistemas Operacionais Linux
  97 +
  98 +Siga os passos a seguir para instalar a biblioteca libzmq em sistemas Linux.
  99 +
  100 + 1. Obtenha uma cópia do código fonte da biblioteca "libzmq", v3.2.5, aqui: http://zeromq.org/intro:get-the-software.
  101 + 2. Construa e instale a biblioteca "libzmq.so" seguindo as instruções aqui: http://zeromq.org/intro:get-the-software#toc7.
  102 + 3. Pronto!
  103 +
  104 +### 3.2. Compilação
  105 +
  106 + Para compilar o programa "Runner" siga os passos a seguir:
  107 +
  108 + 1. Obtenha uma cópia do código fonte: https://github.com/lacs-ufpa/free-mtrix.git.
  109 + 2. Instale a biblioteca libzmq.
  110 + 3. Instale o Lazarus (Interface de Desenvolvimento Rápido de Aplicações) versão 1.6.2 ou superior.
  111 + - No Windows instale necessariamente a versão 32 bits do Lazarus ou, alternativamente, instale a versão 64 bits e implemente o suporte para a plataforma.
  112 + - Em sistemas Linux, recomenda-se a versão 64 bits do Lazarus.
  113 + 4. Execute o Lazarus.
  114 + 5. Abra o arquivo "experiment_runner.lpi" localizado na pasta "experiment_runner" por meio da interface gráfica do Lazarus.
  115 + 6. Execute o comando "compilar" do Lazarus (por exemplo, apertando F9).
  116 +
  117 +### 3.3. Execução
  118 +
  119 +#### 3.3.1. Windows
  120 +
  121 + Nos sistemas operacionais Windows, `Runner` é executado por meio do arquivo `experiment_runner.exe`, localizado na pasta `experiment_runner\`. Recomenda-se a execução no Windows 10, 32 bits.
  122 +
  123 +#### 3.3.2. Sistemas Operacionais Linux
  124 +
  125 + Nos sistemas operacionais Linux, `Runner` é executado por meio do arquivo `experiment_runner`, localizado na pasta `experiment_runner/`. Recomenda-se a execução no Debian 8, 64 bits.
  126 +
  127 +#### 3.3.3. Observações para todos os sistemas
  128 +
  129 + - Se você possui um firewall ligado, you necessitará criar uma regra adicionando o programa como uma exceção.
  130 +
  131 + - Você necessitará de uma instância do programa sendo executada como Servidor (Pesquisador) antes de executar instâncias como Clientes (Participantes). O programa funciona com no mínimo 2 clientes.
  132 +
  133 +### 4. Utilização
  134 +
  135 + Por meio da leitura de arquivos de configuração válidos (gerados pelo programa "Designer" ou não), o programa `Runner` é usado para a apresentação de experimentos aos participantes de uma pesquisa. Um chat integrado ao programa, se habilitado no arquivo de configuração, permite a interação entre os participantes por meio de texto. Os participantes devem ser instruidos a realizar uma tarefa de escolha apresentada pelo programa. O registro das escolhas e da interação é automático e em tempo real. O programa pode ser executado em um único computador, para testes e debug por exemplo, ou pode ser facilmente configurado em uma rede local com múltiplos computadores.
  136 +
  137 + O programa `Runner` possui seu próprio servidor e cliente embarcados. Veja seguir como executar diferentes instâncias do programa como servidor e cliente.
  138 +
  139 +#### 3.4.1. - Em um único computador
  140 +
  141 + O exemplo a seguir assume que uma instância do programa será executada como um servidor, e três instâncias como participantes em uma mesma máquina. Também se assume a existência de um arquivo de configuração chamado `experimento_x.ini`, um experimento de nome `Experimento_X` configurado para 3 participantes e feito por um pesquisador de nome `Pesquisador_X`.
  142 +
  143 + 1. Instale a biblioteca libzmq na máquina alvo.
  144 + 2. Copie o executável `experiment_runner` para diferentes pastas (se Windows, também copie a biblioteca `libzmq`). Por exemplo, no Linux a estrutura de arquivos ficaria assim:
  145 +
  146 +```
  147 + ~/Servidor/experiment_runner
  148 + ~/Participante1/experiment_runner
  149 + ~/Participante2/experiment_runner
  150 + ~/Participante3/experiment_runner
  151 +```
  152 + OBS.: Para facilitar a comunicação, os diferentes executáveis de cada diretório serão chamados pelo nome do próprio diretório que os contém como Servidor, Participante1, Participante2 e Participante3.
  153 +
  154 + 3. Execute o Servidor e pressione o botão `Pesquisador`.
  155 + 4. Pressione o botão `Carregar` na caixa `Pesquisador` à direita e carregue o arquivo de configuração `experimento_x.ini`.
  156 + 5. Execute o Participante1 e pressione o botão `Participante`.
  157 + - repita a operação para o Participante2 e o Participante3.
  158 + 6. Pronto! O experimento está sendo executado, os três participantes podem executar a tarefa e o Servidor pode monitorá-los!
  159 + 7. Ao final do experimento os arquivos de dados (`000.data` e `000.chat`) podem ser conferidos no diretório:
  160 + - ~/Servidor/Pesquisadores/Pesquisador_X/Experimento_X/
  161 +
  162 +#### 3.4.2. - Em uma rede local
  163 +
  164 + O exemplo a seguir assume que diferentes instâncias do programa, sendo um servidor e três clientes, serão executadas em 4 diferentes máquinas de uma rede local. Também se assume que a máquina executando o servidor possui o ip `192.168.1.100`, se assume um arquivo de configuração chamado `experimento_x.ini`, um experimento de nome `Experimento_X` configurado para três participantes e feito por um pesquisador de nome `Pesquisador_X`.
  165 +
  166 + 1. Copie o executável `experiment_runner` para um diretório e instale a biblioteca libzmq em cada máquina, por exemplo:
  167 +
  168 +```
  169 + terminal@Máquina1$~/Servidor/experiment_runner
  170 + terminal@Máquina2$~/Participante1/experiment_runner
  171 + terminal@Máquina3$~/Participante2/experiment_runner
  172 + terminal@Máquina4$~/Participante3/experiment_runner
  173 +```
  174 +
  175 + OBS.: Para facilitar a comunicação, os diferentes executáveis de cada diretório serão chamados pelo nome do próprio diretório que os contém como Servidor, Participante1, Participante2 e Participante3.
  176 +
  177 + 2. Os participantes devem saber aonde o servidor está. Para isso, crie um arquivo de texto chamado `IP` no diretório de cada participante. Na primeira linha do arquivo `IP` escreva o endereço ip do servidor, neste caso `192.168.1.100`.
  178 + 3. Execute o Servidor e pressione o botão `Pesquisador`.
  179 + 4. Pressione o botão `Carregar` na caixa `Pesquisador` à direita e carregue o arquivo de configuração `experimento_x.ini`.
  180 + 5. Execute o Participante1 e pressione o botão `Participante`.
  181 + - repita a operação para o Participante2 e o Participante3.
  182 + 6. Pronto! O experimento está sendo executado, os três participantes podem executar a tarefa e o Servidor pode monitorá-los!
  183 + 7. Ao final do experimento os arquivos de dados (`000.data` e `000.chat`) podem ser conferidos no diretório:
  184 + - terminal@Máquina1$~/Servidor/Pesquisadores/Pesquisador_X/Experimento_X/
  185 +
  186 +## 4. Problemas conhecidos e soluções.
  187 +
  188 +### 4.1. Uma referência foi retornada do servidor.
  189 +
  190 + Esse erro pode ocorrer apenas no Windows.
  191 +
  192 + - Solução 1: Clique com o botão direito sobre o executável e selecione propriedades. Na aba "compatibilidade", marque a caixa "Executar como administrador".
  193 +
  194 +## 5. Referências
  195 +
  196 +Vichi, C., Andery, M. A. P. A., & Glenn, S. S. (2009). A metacontingency experiment: the effects of contingent consequences on patterns of interlocking contingencies reinforcement. Behavioral and Social Issues, 18, 41-57. doi: 10.5210/bsi.v18i1.2292
0 197 \ No newline at end of file
... ...