# Quick Start
Compile Solidity contracts.
## Dependencies
- [python3](https://www.python.org/downloads) version 3.8 up to 3.12.
## Installation
### via `pip`
You can install the latest release via [`pip`](https://pypi.org/project/pip/):
```bash
pip install ape-solidity
```
### via `setuptools`
You can clone the repository and use [`setuptools`](https://github.com/pypa/setuptools) for the most up-to-date version:
```bash
git clone https://github.com/ApeWorX/ape-solidity.git
cd ape-solidity
python3 setup.py install
```
## Quick Usage
In your project, make sure you have a `contracts/` directory containing Solidity files (`.sol`).
Then, while this plugin is installed, compile your contracts:
```bash
ape compile
```
The byte-code and ABI for your contracts should now exist in a `__local__.json` file in a `.build/` directory.
### Solidity Versioning
By default, `ape-solidity` tries to use the best versions of Solidity by looking at all the source files' pragma specifications.
However, it is often better to specify a version directly.
If you know the best version to use, set it in your `ape-config.yaml`, like this:
```yaml
solidity:
version: 0.8.14
```
### EVM Versioning
By default, `ape-solidity` will use whatever version of EVM rules are set as default in the compiler version that gets used.
Sometimes, you might want to use a different version, such as deploying on Arbitrum or Optimism where new opcodes are not supported yet.
If you want to require a different version of EVM rules to use in the configuration of the compiler, set it in your `ape-config.yaml` like this:
```yaml
solidity:
evm_version: paris
```
### Dependency Mapping
To configure import remapping, use your project's `ape-config.yaml` file:
```yaml
solidity:
import_remapping:
- "@openzeppelin=path/to/open_zeppelin/contracts"
```
If you are using the `dependencies:` key in your `ape-config.yaml`, `ape` can automatically
search those dependencies for the path.
```yaml
dependencies:
- name: OpenZeppelin
github: OpenZeppelin/openzeppelin-contracts
version: 4.4.2
solidity:
import_remapping:
- "@openzeppelin=OpenZeppelin/4.4.2"
```
Once you have your dependencies configured, you can import packages using your import keys:
```solidity
import "@openzeppelin/token/ERC721/ERC721.sol";
```
### Library Linking
To compile contracts that use libraries, you need to add the libraries first.
Use the `add_library()` method from the `ape-solidity` compiler class to add the library.
A typical flow is:
1. Deploy the library.
2. Call `add_library()` using the Solidity compiler plugin, which will also re-compile contracts that need the library.
3. Deploy and use contracts that require the library.
For example:
```python
import pytest
@pytest.fixture
def contract(accounts, project, compilers):
# Deploy the library.
account = accounts[0]
library = project.Set.deploy(sender=account)
# Add the library to Solidity (re-compiles contracts that use the library).
compilers.solidity.add_library(library)
# Deploy the contract that uses the library.
return project.C.deploy(sender=account)
```
### Compiler Settings
When using `ape-solidity`, your project's manifest's compiler settings will include standard JSON output.
You should have one listed `compiler` per `solc` version used in your project.
You can view your current project manifest, including the compiler settings, by doing:
```python
from ape import project
manifest = project.extract_manifest()
for compiler_entry in manifest.compilers:
print(compiler_entry.version)
print(compiler_entry.settings)
```
**NOTE**: These are the settings used during contract verification when using the [Etherscan plugin](https://github.com/ApeWorX/ape-etherscan).
#### `--via-IR` Yul IR Compilation Pipeline
You can enable `solc`'s `--via-IR` flag by adding the following values to your `ape-config.yaml`
```yaml
solidity:
via_ir: True
```
### Contract Flattening
`ape-solidity` has contract-flattening capabilities.
If you are publishing contracts using Ape, Ape automatically detects and uses the flattened-contract approach if needed.
To manually flatten a contract for your own benefit, use the following code:
```python
from ape import compilers, project
source_path = project.source_paths[0] # Replace with your path.
flattened_src = compilers.flatten_contract(source_path)
print(str(flattened_src))
```
Raw data
{
"_id": null,
"home_page": "https://github.com/ApeWorX/ape-solidity",
"name": "ape-solidity",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.8",
"maintainer_email": null,
"keywords": "ethereum",
"author": "ApeWorX Ltd.",
"author_email": "admin@apeworx.io",
"download_url": "https://files.pythonhosted.org/packages/05/08/a6eae2b56942e3aa17127afc28cb8e5d42c69e555eae053ea8f267d485f9/ape-solidity-0.7.3.tar.gz",
"platform": null,
"description": "# Quick Start\n\nCompile Solidity contracts.\n\n## Dependencies\n\n- [python3](https://www.python.org/downloads) version 3.8 up to 3.12.\n\n## Installation\n\n### via `pip`\n\nYou can install the latest release via [`pip`](https://pypi.org/project/pip/):\n\n```bash\npip install ape-solidity\n```\n\n### via `setuptools`\n\nYou can clone the repository and use [`setuptools`](https://github.com/pypa/setuptools) for the most up-to-date version:\n\n```bash\ngit clone https://github.com/ApeWorX/ape-solidity.git\ncd ape-solidity\npython3 setup.py install\n```\n\n## Quick Usage\n\nIn your project, make sure you have a `contracts/` directory containing Solidity files (`.sol`).\n\nThen, while this plugin is installed, compile your contracts:\n\n```bash\nape compile\n```\n\nThe byte-code and ABI for your contracts should now exist in a `__local__.json` file in a `.build/` directory.\n\n### Solidity Versioning\n\nBy default, `ape-solidity` tries to use the best versions of Solidity by looking at all the source files' pragma specifications.\nHowever, it is often better to specify a version directly.\nIf you know the best version to use, set it in your `ape-config.yaml`, like this:\n\n```yaml\nsolidity:\n version: 0.8.14\n```\n\n### EVM Versioning\n\nBy default, `ape-solidity` will use whatever version of EVM rules are set as default in the compiler version that gets used.\nSometimes, you might want to use a different version, such as deploying on Arbitrum or Optimism where new opcodes are not supported yet.\nIf you want to require a different version of EVM rules to use in the configuration of the compiler, set it in your `ape-config.yaml` like this:\n\n```yaml\nsolidity:\n evm_version: paris\n```\n\n### Dependency Mapping\n\nTo configure import remapping, use your project's `ape-config.yaml` file:\n\n```yaml\nsolidity:\n import_remapping:\n - \"@openzeppelin=path/to/open_zeppelin/contracts\"\n```\n\nIf you are using the `dependencies:` key in your `ape-config.yaml`, `ape` can automatically\nsearch those dependencies for the path.\n\n```yaml\ndependencies:\n - name: OpenZeppelin\n github: OpenZeppelin/openzeppelin-contracts\n version: 4.4.2\n\nsolidity:\n import_remapping:\n - \"@openzeppelin=OpenZeppelin/4.4.2\"\n```\n\nOnce you have your dependencies configured, you can import packages using your import keys:\n\n```solidity\nimport \"@openzeppelin/token/ERC721/ERC721.sol\";\n```\n\n### Library Linking\n\nTo compile contracts that use libraries, you need to add the libraries first.\nUse the `add_library()` method from the `ape-solidity` compiler class to add the library.\nA typical flow is:\n\n1. Deploy the library.\n2. Call `add_library()` using the Solidity compiler plugin, which will also re-compile contracts that need the library.\n3. Deploy and use contracts that require the library.\n\nFor example:\n\n```python\nimport pytest\n\n\n@pytest.fixture\ndef contract(accounts, project, compilers):\n # Deploy the library.\n account = accounts[0]\n library = project.Set.deploy(sender=account)\n\n # Add the library to Solidity (re-compiles contracts that use the library).\n compilers.solidity.add_library(library)\n\n # Deploy the contract that uses the library.\n return project.C.deploy(sender=account)\n```\n\n### Compiler Settings\n\nWhen using `ape-solidity`, your project's manifest's compiler settings will include standard JSON output.\nYou should have one listed `compiler` per `solc` version used in your project.\nYou can view your current project manifest, including the compiler settings, by doing:\n\n```python\nfrom ape import project\n\nmanifest = project.extract_manifest()\n\nfor compiler_entry in manifest.compilers:\n print(compiler_entry.version)\n print(compiler_entry.settings)\n```\n\n**NOTE**: These are the settings used during contract verification when using the [Etherscan plugin](https://github.com/ApeWorX/ape-etherscan).\n\n#### `--via-IR` Yul IR Compilation Pipeline\n\nYou can enable `solc`'s `--via-IR` flag by adding the following values to your `ape-config.yaml`\n\n```yaml\nsolidity:\n via_ir: True\n```\n\n### Contract Flattening\n\n`ape-solidity` has contract-flattening capabilities.\nIf you are publishing contracts using Ape, Ape automatically detects and uses the flattened-contract approach if needed.\n\nTo manually flatten a contract for your own benefit, use the following code:\n\n```python\nfrom ape import compilers, project\n\nsource_path = project.source_paths[0] # Replace with your path.\nflattened_src = compilers.flatten_contract(source_path)\nprint(str(flattened_src))\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Plugin for Ape Ethereum Framework for compiling Solidity contracts",
"version": "0.7.3",
"project_urls": {
"Homepage": "https://github.com/ApeWorX/ape-solidity"
},
"split_keywords": [
"ethereum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "42a65fe8dbfc55ec73d85a51b741c96a16853bcb16acedbfbec4a87d7fcce634",
"md5": "2013bc83379393cfc13b72e84aa2d857",
"sha256": "9dd6ceea4fe19b407ab42dbe75120820d9d0e162e6e4f895207ebf4f93c7a317"
},
"downloads": -1,
"filename": "ape_solidity-0.7.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2013bc83379393cfc13b72e84aa2d857",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8",
"size": 24408,
"upload_time": "2024-04-30T22:38:48",
"upload_time_iso_8601": "2024-04-30T22:38:48.905291Z",
"url": "https://files.pythonhosted.org/packages/42/a6/5fe8dbfc55ec73d85a51b741c96a16853bcb16acedbfbec4a87d7fcce634/ape_solidity-0.7.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0508a6eae2b56942e3aa17127afc28cb8e5d42c69e555eae053ea8f267d485f9",
"md5": "4c1835394c52f2f07f17c4a0d077cc84",
"sha256": "87b2ce58e0b2d4d8b3a74311cca82fead6856a453ea1ad109964c367268d0154"
},
"downloads": -1,
"filename": "ape-solidity-0.7.3.tar.gz",
"has_sig": false,
"md5_digest": "4c1835394c52f2f07f17c4a0d077cc84",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8",
"size": 411921,
"upload_time": "2024-04-30T22:38:50",
"upload_time_iso_8601": "2024-04-30T22:38:50.784074Z",
"url": "https://files.pythonhosted.org/packages/05/08/a6eae2b56942e3aa17127afc28cb8e5d42c69e555eae053ea8f267d485f9/ape-solidity-0.7.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-30 22:38:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ApeWorX",
"github_project": "ape-solidity",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ape-solidity"
}
JSON
